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PREFACE 

This manual, the PL/M Programmer's Guide, describes the PL/M-86, PL/M-286 and 
PL/M-386 languages and gives instructions for using the corresponding PL/M com- 
pilers. The PL/M Programmer's Guide assumes basic familiarity with programming 
concepts, including structured programming. It is organized as follows: 

• Chapter 1 is an overview of the PL/M language. It includes an introductory 
sample program. 

• Chapter 2 defines the basic elements of the PL/M language. 

• Chapter 3 concerns types, declarations, variables, and related topics. 

• Chapter 4 summarizes the rules for declaring and referencing arrays and 
structures. 

• Chapter 5 describes expressions and assignment statements. 

• Chapter 6 concerns the statements that control the flow of program execution. 

• Chapter 7 discusses block structure and scope. 

• Chapter 8 describes procedure declaration, activation, and attributes. 

• Chapter 9 concerns built-in procedures, functions, and variables. 

• Chapter 10 describes the built-in functions that manipulate the target micropro- 
cessor and numeric coprocessor. 

• Chapter 1 1 explains each of the compiler controls and their effect on compiler 
output. 

• Chapter 12 presents an annotated sample PL/M-86 program. 

• Chapter 13 discusses the extended segmentation models and controls. 

• Chapter 14 lists the error and warning messages and provides brief explanations 
of the messages. 

• Appendix A lists reserved words and predeclared identifiers. 

• Appendix B summarizes program limits. 

• Appendix C is a formal summary of PL/M syntax. 

• Appendix D summarizes the differences among various dialects of PL/M. 

• Appendix E is an ASCII-character table that also identifies which are PL/M 
characters. 

xvii 



• Appendix F explains how to link to modules written in other languages. 

• Appendix G discusses run-time interrupt processing. 

• Appendix H summarizes the libraries supplied with PL/M. 

Note that throughout this manual, the general term PL/M refers to PL/M-86, 
PL/M-286, and PL/M-386. Information that is peculiar to a particular PL/M com- 
piler is flagged with the notation shown below. 

PL/M-### 



— PL/M-### 

Related Publications 

To use a PL/M-86, PL/M-286, or PL/M-386 compiler on any supported host, you 
need the PL/M Programmer's Guide (this manual) and one of the following host- 
oriented supplements. 

DOS Supplement for the PL/M Programmer's Guide, order number 452 162 
VAX/VMS Supplement for the PL/M Programmer's Guide, order number 480609 
XENIX Supplement for the PL/M Programmer's Guide, order number 452165 
iRMX® Supplement for the PL/M Programmer's Guide, order number 452164 
ISIS/iNDX Supplement for the PL/M Programmer's Guide, order number 452163 
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INTRODUCTION 

This chapter introduces the PL/M-86, PL/M-286, and PL/M-386 languages and ex- 
plains the process of developing software for execution by an 8086/801 86-, 80286- , 
or 80386-based system. 

1.1 Product Definition 

PL/M is a high-level language for programming Intel microprocessors. It was 
designed by Intel Corporation to meet the software requirements of computers in a 
wide variety of systems and applications work. 

The PL/M compilers are software tools that translate PL/M source code into relocat- 
able object modules. These modules can then be combined with other modules coded 
in PL/M, assembly language, or other high-level languages. The compilers provide 
listing output, error messages, and a number of compiler controls that aid in develop- 
ing and debugging programs. 

You can use LINK86, BND286, or BND386 to combine the program modules, and 
locate the programs with LOC86 or the 80286 or 80386 System Builder. You can then 
combine the resulting relocatable object modules with the necessary support 
libraries. 

After the program modules are combined and located, you can use an in-circuit emu- 
lator (e.g., the ICE™-386 emulator) or a software debugging utility (e.g., PSCOPE) 
to debug the program. 

For firmware systems, to transfer the program to PROM, use the Universal PROM 
Programmer (iUPP) and the Universal PROM Mapper (UPM) software. 



1 .2 Advantages of Using the PL/M 




PL/M programs are portable, which means that they are easily transferred from one 
microprocessor to another. When using PL/M, you need not be concerned with the 
instruction set of the target processor. Additionally, there is no need to be concerned 
with other details of the target processor, such as register allocation or assigning the 



proper number of bytes for each data item. The PL/M compilers do these functions 
automatically. PL/M keywords and phrases are close to natural English, and many 
operations (including arithmetic and Boolean operations) can be combined into ex- 
pressions. This enables the execution of a sequence of operations with just one pro- 
gram statement. Data types and data structures are close to the actual problem. For 
instance, in PL/M, the program can be written in terms of Boolean expressions, 
characters, and data structures, in addition to bytes, words, and integers. The intro- 
ductory example at the end of this chapter illustrates these points. 

Coding programs in a high-level language rather than assembly language involves 
thinking closer to the level used when planning the overall system design. Following 
is a list of the advantages of using PL/M, and the applications for which PL/M is best 
suited: 

• PL/M block structure and control constructs aid and encourage structured 
programming. 

• PL/M has facilities for data structures such as structured arrays and pointer- 
based dynamic variables. 

• PL/M is a typed language. The compiler does data type compatibility checking 
during compilation to help detect logic errors in programs. 

• PL/M data structuring facilities and control statements are designed in a logi- 
cally consistent way. Thus, PL/M is a good language for expressing algorithms 
for systems programming. 

• PL/M is a standard language used on Intel microcomputers. PL/M programs are 
upwardly compatible across the 80[x]86 family of microprocessors. 

• PL/M was designed for programmers (generally systems programmers) who 
need access to the microprocessor's features such as indirect addressing and 
direct I/O for optimum use of all system resources. 

In comparison with other languages, PL/M has more features than BASIC and is a 
more general-purpose language than either FORTRAN (best suited for scientific 
applications) or COBOL (designed for business data processing). PL/M accesses the 
microprocessor hardware features more easily than C. Additionally, in comparison to 
C, PL/M offers the ability to nest procedures and the program structure is easier to 
maintain. 
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The Structure of a PL/M Program 



PL/M is a block-structured language; every statement in a program is part of at least 
one block. A block is a well-defined group of statements that begins with a DO 
statement or a procedure declaration and ends with an END statement. 

A module is a labeled simple DO-block. A module must begin with a labeled DO 
statement and end with an END statement. Between the DO statement and the END 
statement other statements provide the definitions of data and processes that make up 
the program. These statements are said to be part of the block, contained within the 
block, or nested within the block. A module can contain other blocks but is never 
itself contained within another block. See Chapter 6 for a description of DO-blocks. 

Every PL/M program consists of one or more modules, separately compiled, each 
consisting of one or more blocks. The two kinds of blocks are DO-blocks and proce- 
dure definition blocks. 

A procedure definition block is a set of statements beginning with a procedure decla- 
ration and ending with an END statement. Other declarations and executable state- 
ments can be placed between these points, and are used later when the procedure is 
actually invoked or called into execution. The definition block is a further declaration 
of everything the procedure will use and do. 



The two types of statements in PL/M are declarations and executable statements. All 
PL/M statements end with a semicolon (;). 

1.4.1 Declaration Statements 

The following is a simple example of a declaration statement: 
DECLARE WIDTH BYTEi 

This statement introduces the identifier WIDTH and associates it with the contents of 
1 byte (8 bits) of memory. Now, rather than having to know the memory address of 
this byte, you can refer to it by the name WIDTH. 

A group of statements intended to perform a function (i.e., a subprogram or subrou- 
tine) can be given a name by declaring them to be a procedure: 

ADDER_UPPER: PROCEDURE (BETA) BYTE n 
Introduction 1-3 
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Overview of PL/M Statements 



The statements that define the procedure follow the semicolon. This block of PL/M 
statements is invoked from other points in the program, and may involve passing 
parameters to the program. When a procedure has finished executing, control is 
returned immediately to the main program. This capability is the major feature 
enabling modular program construction. 

1 .4.2 Executable Statements 

The following is an example of an executable statement: 
CLEARANCE = WIDTH + 2; 

The two identifiers, CLEARANCE and WIDTH, must be declared prior to this exe- 
cutable statement, which produces machine code to retrieve the WIDTH value from 
memory. Once the WIDTH value is obtained, 2 is added to it and the sum is stored in 
the memory location for CLEARANCE. 

For most purposes, it is unnecessary to think in terms of memory locations when 
programming in PL/M. CLEARANCE and WIDTH are variables, and the assign- 
ment statement assigns the value of the expression WIDTH + 2 to the variable 
CLEARANCE. The compiler automatically generates all the machine code neces- 
sary to retrieve data from memory, to evaluate the expression retrieved, and to store 
the result in the proper location. 

Executable statements are discussed in the following chapters: 



Assignment Statement 


Chapter 


5 


CALL Statement 


Chapter 


8 


CAUSE$INTERRUPT Statement 


Chapter 


10 


DISABLE Statement 


Chapter 


10 


DO CASE Statement 


Chapter 


6 


DO WHILE Statement 


Chapter 


6 


ENABLE Statement 


Chapter 


10 


END Statement 


Chapter 


6 


Executable Functions 


Chapter 


9 


GOTO Statement 


Chapter 


6 


HALT Statement 


Chapter 


10 


IF Statement 


Chapter 


6 


Iterative DO Statement 


Chapter 


6 


Nested IF Statement 


Chapter 


6 


RETURN Statement 


Chapter 


8 


Simple DO Statement 


Chapter 


6 



1-4 



Introduction 



1.4.3 Built-in Procedures and Variables 



PL/M provides a variety of built-in procedures and variables. These include functions 
such as shifts and rotations, data type conversions, executable functions, block I/O, 
real math, and string manipulation (see Chapters 9 and 10 for details). 

1.4.4 Overview of PL/M Expressions 

A PL/M expression is made up of operands and operators, and resembles a conven- 
tional algebraic expression. 

Operands include numeric constants (such as 3.78 or 105) and variables (as well as 
other types discussed in Chapters 3 and 5). The operators include + and — for 
addition and subtraction, * and / for multiplication and division, and MOD for 
modulo arithmetic. 

As in an algebraic expression, elements of a PL/M expression can be grouped with 
parentheses. 

An expression is evaluated using unsigned binary arithmetic, signed integer arithme- 
tic, and/or floating-point arithmetic, depending on the types of operands in the ex- 
pression (see Chapters 3 and 5). 

1.4.5 Input and Output 

PL/M does not provide formatted I/O capabilities like those of FORTRAN, BASIC, 
or COBOL. However, PL/M does provide built-in functions for direct I/O that do not 
require operating system run-time support. In PL/M-86, these built-in functions al- 
low for single-byte or single-word I/O. In PL/M-286 (and in PL/M-86 programs 
compiled for execution on an 80186-based system), these built-in functions allow for 
single-byte or word I/O, and block I/O (for strings of bytes or single words). In 
PL/M-386, these built-in functions allow for single-byte, half-word or word I/O, as 
well as for block I/O (for strings of bytes, half-words, or single-words) . For detailed 
information on these I/O functions, see Chapter 10. 

1 .5 An Introductory Sample Program 

Figure 1-1 shows a sample PL/M-86 program. This program contains many unde- 
fined words and constructs that will be explained in the upcoming chapters. 
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The main program does little but define data and call the procedure named 
SORTPROC. To prepare this sample program for execution, type the program using 
a text editor. 

To compile the module, if the file PROG 1 A. SRC contains the module SORTPROC 
and the compiler and your source file are in the current directory, invoke the compiler 
with the following command: 
PLMfib PROGlA-SRC<cr> 

Host systems vary in their invocation procedures. The compiler responds with the 
following sign-on message: 

system-id PL/M-flb COMPILER Vx-y 
Where: 

system-id is the host operating system name. 

x-y is the compiler version number. 

This is normally followed by the console sign-off message: 

PL/M-flb COMPILATION COMPLETE ■ n WARNINGS]-, m ERR0R[S] 

Where: 

n and m represent the number of warning and nonfatal error messages gener- 
ated during compilation. 

NOTE 

To generate and output sort data, user-supplied routines must be added to this 
program in the areas indicated. 

For example, interfacing with the operating system can be done using UDI calls 
(e.g., DQ$WRITE, DQ$EXIT). 

Interface routines must be used to exit to the system and return control to the 
host operating system (e.g., DQ$EXIT in UDI). Each operating environment 
has its own set of interface routines. 
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system-id PL/M-AL Vx-y COMPILATION OF MODULE SORTriODULE 

OBJECT HODULE PLACED IN progla-obj 

COMPILER INVOKED BY: path PLMAb . Ah progla-src PUCSD) 

1 SORTMODULE: DOi /* Beginning of module */ 

2 1 MOVBYTES ■ PROCEDURE (SRC*PTR, DESTSPTR, SIZE), 

3 1 DECLARE (SRC$PTR,DEST$PTR) POINTER, 

SIZE WORD; 

4 5 IF (SRC$PTR > DEST$PTR) THEN 

5 2 CALL MOVB(SRC$PTR-,DEST$PTR n SIZE)n 
L S ELSE 

CALL MOVRB (SRC$PTR,DEST$PTR,SIZE) i 
7 2 END MOVBYTES, 

A 1 SORTPROC: PROCEDURE (PTR, COUNT, RSIZE, KEY) i 

I 2 DECLARE PTR POINTER, (COUNT-, RSIZE, KEY) WORD, 

/* Parameters: 

PTR is pointer to first record- 
COUNT is number of records to be 
RSIZE is number of bytes in each 

max is ISA- 
KEY is byte position within each 
scalar to be used as sort key- 
ID 2 DECLARE REC BASED PTR(l) BYTE, 
CUR (12A) BYTE, 
(I, J) WORD i 

II 2 SORT: 

DO J = 1 TO COUNT - 1", 

12 3 CALL M0VBYTES(5IREC<J*RSIZE), 3CUR, RSIZE) i 

13 3 I = Ji 

14 3 DO WHILE I > D 

AND (REC URSIZE + KEY) > CUR(KEY) ) , 

15 4 CALL MOVBYTESORECt (I-1)*RSIZE), 

3REC(I*RSIZE), RSIZE) i 

Figure 1-1 Sample Program: Module Sort 



sorted ■ 
record, 

record of a BYTE 
*/ 
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ik i to 

17 4 END i 

Ifl 3 CALL nOVBYTESOCUR-, 3REC ( I*RSIZE ) -, RSIZE ) =, 

n 3 END SORT 

ED S END SORTPROCn 

/* Program to sort two sets of records i using SORTPROC - */ 

El 1 DECLARE SETM50) STRUCTURE ( 
ALPHA WORD-, 
BETA (IE) WORD i 
GAMMA INTEGER, 
DELTA REAL-, 
EPSILON BYTE) i 

EE 1 DECLARE SETE(SDD) STRUCTURE ( 
ITEMS(El) INTEGER 
VOLTS REALn 
KEY BYTE) ^ 

/* Data is read in to initialize the records- */ 

E3 1 CALL SORTPROCOSETln LENGTH(SETl) i SIZE ( SET1 (0 ) ) •, 
SIZE(SETKD) .ALPHA) >i 

E4 1 CALL SORTPROCtSSETE, LENGTH(SETE) , SIZE(SETS(D) ) 

(SIZE(SETEtD) )-SIZE(SETE(D) -KEY) ) M 

ES 1 END SORTMODULE; /* End of module */ 

Figure 1-1 Sample Program: Module Sort (continued) 
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IIODULE INFORfl ATION : 



CODE AREA SIZE 
CONSTANT AREA SIZE 
VARIABLE AREA SIZE 

riAxmun stack size 

LINES READ 
D PROGRAM WARNINGS 
D PROGRAP1 ERRORS 



= DDFBH 5S1D 

= DDODH DD 

= b2C5H 5S265D 

= QDlflH 



DICTIONARY SUHHARY : 



471KB flEHORY AVAILABLE 
4KB DISK SPACE USED 
DKB DISK SPACE USED 



END OF PL/n-Ab COtlPILATION 



Figure 1-1 Sample Program: Module Sort (continued) 
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LANGUAGE ELEMENTS 

PL/M-86, -286 and -386 programs are "free-form", meaning that there are no re- 
strictions on where you place a statement on a line. You can use as many blanks 
(spaces) as necessary to format your program for readability. 

2.1 Character Set 

The PL/M-86/286/386 source program character set is the following subset of the 
ASCII character set: 

A . . Z 
a . . z 
. . 9 

and the following special characters: 

= ./()+-'*,<>:;©$_ 

and the blank (space), tab, carriage-return and line-feed characters. (Appendix E 
indicates whether each ASCII character is a member of the PL/M character set, and 
gives its hexadecimal value.) 

PL/M does not distinguish between uppercase and lowercase letters, except in string 
constants. For example, the variable names "xyz" and "XYZ" are the same. (In this 
manual, all PL/M syntax is uppercase, by convention.) 

Special characters have particular meaning in PL/M, as explained throughout this 
manual. Table 2-1 summarizes the meaning of special characters in PL/M. 

The PL/M compilers treat multiple contiguous blanks in PL/M source programs as 
single blanks, by ignoring all the blanks except the first one. 

The PL/M compiler produce an error or warning message whenever they encounter a 
character other than those described above in a source program 

In addition to the source character set, PL/M allows the use of special character sets 
(such as Kanji characters), located from 0080H through OOFFH (excluding 008 1H). 
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Table 2-1 PL/M Special Characters 



Symbol 


Name 


Use 






Two rti^tinrt ij^p^' 




(1) assignment operator 

(2) relational test operator 




assign 


embedded assignment operator 


@ 


at-sign 


location reference operator 




aoi 


Three distinct uses: 
f"H dprimal nnint 

III VJd^MIICll f-l \-/ 1 1 1 L 

(2) structure member qualification 

(3) address operator 


/ 


slash 


division operator 


/* 




beginning-of-comment delimiter 


*/ 




pnd-of-rommpnt dplimitpr 


( 


Ipft narpn 


Ipft dplimitpr of lists suh^rrints and snmp 
expressions 


) 


right paren 


right delimiter of lists, subscripts, and some 
expressions 


+ 


plus 


addition or unary plus operator 




mini 19 

Mill IUO 


91 intra ft ion or iinarv minu^ nnprator 






Qtrinn Hplimitpr 
oil ii i y uciii unci 


* 


CaO ICI IOl\ 


Two distinct ii<?p<;' 

(1) multiplication operator 

(2) implicit dimension specifier 


< 


less than 


relational test operator 


> 


greater than 


relational test operator 


< = 


less or equal 


relational test operator 


> = 


greater or 
equal 


relational test operator 


< > 


not equal 


relational test operator 




colon 


label terminator 


J 


semicolon 


statement terminator 


I 


comma 


list element delimiter 




underscore 


significant character in identifier 


$ 


dollar sign 


Two distinct uses: 

(1) non-significant character embedded 
within number or identifier 

(2) significant as the first character 
on a control line in a source file 
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2.2 Tokens, Separators, and the Use of Blanks 

The smallest meaningful unit of a PL/M statement is a token. Every token belongs to 
one of the following classes: 

• Identifiers 

• Reserved words 

• Simple delimiters (all of the special characters, except the dollar sign, are simple 
delimiters) 

• Compound delimiters (combinations of two special characters): 
<>, <=, >=,: = ,/*,*/ 

• Numeric constants 

• Character string constants 

It is usually clear where one token ends and the next one begins. For example, in the 
assignment statement: 

EXACT=APPR0X*(HEIGHT-3)/SCALEi 

EXACT, APPROX, HEIGHT, and SCALE are identifiers, 3 is a numeric constant, 
and all the other characters are simple delimiters. 

If a delimiter (simple or compound) does not naturally occur between two tokens, you 
must separate them with one or more blank(s). 

A comment can also be used as a separator. 

Blanks can be inserted around any token without changing the meaning of the PL/M 
statement. Thus, the assignment statement: 

EXACT = APPROX * ( HEIGHT - 3 ) / SCALE; 
is equivalent to: 

EXACT = APPR0X*(HEIGHT-3) / SCALE =i 

2.3 Identifiers and Reserved Words 

Identifiers name variables, procedures, symbolic constants, and statements. State- 
ment identifiers are called labels. Identifiers can be up to 31 characters long. The first 
character must be alphabetic or the underscore (_), and the remaining characters may 
be alphabetic, numeric, or the underscore. 
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You can use the dollar sign character to improve the readability of an identifier or 
constant, but the dollar character is not meaningful to the PL/M compilers. An identi- 
fier or constant containing a dollar sign is equivalent to the same identifier without 
the dollar sign. Note that you must not use a dollar character in a procedure name 
within a subsystem definition. (See Chapter 13.) 

Examples of valid identifiers are: 

INPUT_COUNT 
X 

GAMM 

LONGIDENTIFIERNUMBER3 

LONG$$$IDENTIFIER$$$NUMBER$$$3 

_MAIN 

INPUT$COUNT 
INPUTCOUNT 

The long identifiers are identical to the compiler. INPUT$COUNT and 
INPUTCOUNT are interchangeable, but are different from INPUT_COUNT. 

Identifiers must be distinct from reserved words. If you want to use PL/M built-in 
procedures and variables, the identifiers in your source program must be distinct 
from the built-ins' predefined identifiers. Appendix A lists the reserved words and 
predefined identifiers. 

2.4 Constants 

A constant is a value that does not change during a program's execution. The three 
types of constants are whole-number constants, floating-point constants, and charac- 
ter strings. 

2.4.1 Whole-Number Constants 

Whole-number constants can be binary, octal, decimal, or hexadecimal numbers. 
The PL/M compilers interpret numbers without a base suffix as decimal numbers. 
When they encounter characters that are invalid in the specified (or assumed) base, 
the compilers produce appropriate messages. If a constant contains characters invalid 
in the designated number base, it will be flagged as an error. 

A whole-number constant can be an 8-bit, 16-bit or 32-bit value. In PL/M-386, a 
whole-number constant can also be a 64-bit value. The range of whole-number con- 
stants is non-negative. (The minus sign in front of a whole-number constant is not 
part of the constant. 
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The first character of a hexadecimal number must be a numeric digit to avoid looking 
like an identifier. For example, write the hexadecimal form of the decimal value 163 
as "0A3H" (rather than "A3H"); otherwise the compilers will interpret it as an 
identifier. 

Examples of valid whole-number constants are: 

1EAH 2 33(3 1010B SSD 0BF3H bSS3S 7770 3EACH 0F7L.CDSH 

Examples of invalid whole-number constants are: 

IE AF Hexadecimal digits used without an H suffix, and invalid in the default 
decimal interpretation. 

12 AD The final D could be a suffix but the A is not a decimal digit. If 
hexadecimal is intended, a final H is needed. 

11A2B A aed 2 are not valid binary digits. If hexadecimal is intended, a final 
H is necessary. 

2 A D G H G is not a valid hexadecimal digit. 

For example, the maximum whole-number 16-bit constant is: 

2**1L,-1 = 1111$1111$1111$1111B = 1777770 = bSS3SD = DFFFFH 

— PL/M-386 

In the PL/M-386, the maximum whole-number 32-bit constant is: 

2**32-1 = 1111$1111$1111$1111$1111$1111$1111$1111B 
= 37777777777(3 
= H2T4Tb72TSD 

= DFFFFFFFFH end 

— PL/M-386 



2.4.2 Floating-Point Constants 

The presence of a decimal point in a decimal constant creates a floating-point con- 
stant. Floating-point constants are represented in REAL precision (see Section 3.4). 
Only decimal real constants are allowed. 

At least one decimal digit (e.g., 0) must precede the decimal point. A fractional part 
is optional after the decimal point, as is the base-ten exponent, which is indicated by 
the letter E. This exponent must have at least one digit. Note that no fractional expo- 
nents are possible. 
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In PL/M-86 and PL/M-286, the range for floating-point constants is 3.37 x 10**38 
to 1.17 x 10**(-38). 



In PL/M-386, the range is -2**(+128) to -2**(-126), zero, +2**(-126) to 
+ 2**(+ 128). This range is approximately -3.4 x 10**38 to -8.4 x 10**(-37), 
zero, and 8.4 x 10**(-37) to 3.4 x 10**38. 

The following are examples of valid floating-point constants: 

5. 3D 17b- D 1-flfi 3.1M1ST lb. 22S-S 

S3.DE-1 L7bDE2 O-lflflEl 31415T.E-S 1-bE+l 2-222E+2 

Note that plus signs do not change the meaning of exponents. 

The following are examples of invalid floating-point constants: 
b No decimal point 

1 ■ 3 AH Hexadecimal not allowed in floating-point constants 

1 D ■ □ 1 1 B Binary not allowed 
7 - S 2 & Octal not allowed 

4-6E1AH/2 Only decimal constants in exponents; no hexadecimal, no ex- 
pressions, no fractions 



2.4.3 Character Strings 

Character strings are printable ASCII characters enclosed within apostrophes. There 
are two types of character strings: string constants and character constants. A string 
constant is used to initialize variables or to pass a pointer. The maximum length of a 
string constant is 255. A character constant is used in expressions, and its value 
should fit into a double or machine word (32 bits). A string used as a character 
constant can contain from one to four characters. 

To include an apostrophe in a string, write it as two apostrophes (e.g., the string "'Q' 
comprises 2 characters, an apostrophe followed by a Q). Values 0080H through 
00FFH (excluding 008 1H) can be used in a quoted character string. Spaces are al- 
lowed but line-feeds are not. The compiler represents character strings in memory as 
ASCII codes, one 7-bit character code to each 8-bit byte, with a high-order zero bit. 
Strings of length 1 translate to single-byte values. Character constants of length 2 
translate to 16-bit values, and those of length 3 or 4 translate to 32-bit values. For 
example: 

A' is equivalent to 41H 
AG' is equivalent to 4147H 
AGR' is equivalent to 414752H 
AGRX' is equivalent to 41475258H 
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(See Appendix E, ASCII Characters, Hex Values, and PL/M Character Set.) 

Therefore, character constants can be used as 8-bit, 16-bit, or 32-bit values. Charac- 
ter constants longer than 4 characters exceed the 32-bit capacity. 

2.5 Comments 

In PL/M, a comment is a sequence of characters delimited on the left by the character 
pair /* and on the right by the character pair */. These delimiters instruct the com- 
piler to ignore any text between them and to consider such text as not part of the 
program. 

A comment can contain any printable ASCII or special character and can also include 
space, carriage-return, line-feed, and tab characters. If you embed a comment in a 
character string constant, it becomes part of the constant. A comment can appear 
anywhere that a blank character can appear except embedded within a token. 

The following is an example of a PL/M comment: 

/*This procedure copies one structure to another-*/ 

In this manual, comments are presented in lowercase to distinguish them visually 
from program code, which is presented in uppercase. 
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DATA DECLARATIONS, TYPES, 
AND BASED VARIABLES 

In PL/M, you can declare symbolic names for variables, constants, procedures and 
statements ("labels"). For each symbolic name, there must be one declaration at the 
beginning of the block containing the name, or in an outer, enclosing block. A decla- 
ration consists of an identifier, type, attributes and/or location. Multiple declarations 
of a name in a block are invalid. 

The declaration of a variable or constant identifier must precede use of the identifier 
in an executable statement. Although it is not good programming practice, you can 
call a reentrant procedure before defining it. You can either explicitly declare a state- 
ment label, or implicitly declare it by attaching it to an executable statement with a 
colon character. 



Required and optional declaration elements are shown in Table 3-1 . 

Table 3-1 Declaration Elements 



Declaration 
Statements 
For 


Must Use 


Can Use 


Variable 
Names 


BYTE, WORD, DWORD, INTEGER, 
POINTER, SELECTOR, REAL, 
STRUCTURE, ADDRESS* 

Additionally, for PL/M-386: 
HWORD, QWORD, CHARINT, 
SHORTINT, LONGINT, OFFSET 


linkage attributes:** 
PUBLIC or 
EXTERNAL or 
location attributes: 
AT (location reference) 
variable initialization 
attribute: INITIAL 
(value-list) 


Constant 
Names 


type, as above, and constant 
initialization attribute: 
DATA (value-list) 


linkage attributes as 
above 


Label Names 


LABEL 


linkage attributes as 
above 


Macro 

Substitution 

Names 


LITERALLY 'string' 





'ADDRESS is equivalent to the OFFSET data type. 
* * Placement is important (see Section 3.1.1). 
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A DECLARE statement is a nonexecutable statement that introduces some object or 
collection of objects, associates names (and sometimes values) with them, and allo- 
cates storage if necessary. The most important use of DECLARE is for declaring 
variables. 

A variable can be a scalar (i.e., a single quantity), an array, or a structure. 

A scalar variable is a single object whose value may not be known at compile time 
and may change during the execution of the program. 

An array is a list of scalars with the same identifier, the individual objects of which 
are differentiated by subscripts. 

A structure is an aggregate of scalars, arrays and/or structures with the same main 
identifier. The members of a structure are differentiated from each other by their own 
member-identifiers or field names. For example, EMPLOYEES. NAME would refer 
to the NAME field within the structure EMPLOYEES. 

3.1 .1 Sample DECLARE Statements 

Note that when using linkage (PUBLIC/EXTERNAL) and initialization (DATA/ 
INITIAL) attributes, the order of declaration is critical. Place linkage attributes be- 
fore the initialization attribute, and after the type declaration. 

For example: 

DECLARE a$p BYTE PUBLIC INITIAL COi 

The following statements declare scalars: 

DECLARE APPROX REAL; 
DECLARE (OLD-, NED) BYTE i 
DECLARE POINT WORD -i VAL15 B YTE i 

The first example declares a single scalar variable of type REAL, with the identifier 
APPROX. 

The second example declares two scalars, OLD and NEW, both of type BYTE. This 
kind of statement is called a factored declaration, which is similar to the sequence: 

DECLARE OLD BYTE; 
DECLARE NEW BYTE; 
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A factored declaration (for structures and arrays) guarantees that the bytes will be 
contiguously located in memory, which may be useful in real time applications (see 
also Section 3.1.3). Separate declaration statements do not guarantee this. 

The third example declares two scalars of different types: POINT is of type WORD, 
and VAL12 is of type BYTE. 

The following statements declare arrays: 

DECLARE DOMAIN (12fl) BYTE; 
DECLARE GAMMA (IT) DWORD; 

The first example declares the array DOMAIN, with 128 scalar elements of type 
BYTE. These elements are distinguishable by subscripting the name DOMAIN, us- 
ing the range to 127 for the subscripts. For example, the third element of DOMAIN 
can be referred to as DOMAIN (2). The first element of every array has subscript 0. 

The second example declares the array GAMMA, with 19 scalar elements of type 
DWORD. The subscripts for this array can range from to 18. 

The third example declares a structure with two scalar members: 

DECLARE RECORD STRUCTURE (KEY BYTE, INFO WORD); 

The two members are a BYTE scalar that can be referred to as RECORD. KEY and a 
WORD scalar that can be referred to as RECORDINFO. The word named by 
RECORD. INFO is the second and third bytes of this structure. 

Structures are discussed in further detail in Chapter 4. 

3.1 .2 Results of Variable Declarations 

Valid variable declarations result in the following: 

• The name is given a unique address. 

• The variable is considered to have the attributes declared. 

All subsequent uses of the variable in the block where it is declared refer to the same 
address (except for based variables, discussed in Section 3.5). 

A valid variable declaration also requires all references to the variable to conform to 
the rules for the current attributes (i.e., those attributes having priority in the current 
block). Thus, the compiler can flag a large variety of errors caused by incompatible 
references within the current block. The variable reference must be consistent with 
the variable declaration. 
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3.1.3 Combining DECLARE Statements 



A separate DECLARE statement is not required for each declaration. For example, 
instead of writing the two DECLARE statements: 

DECLARE CHR BYTE INITIAL ( * A ' ) i 
DECLARE COUNT INTEGER =, 

Both declarations can be written in a single DECLARE statement, as follows: 
DECLARE CHR BYTE INITIAL ( ' A ' ) ■> COUNT INTEGER i 

This declare statement contains two declaration elements, separated by a comma. 
A declaration element is the text for declaring one identifier (or one factored list 
of identifiers). Every DECLARE statement contains at least one declaration ele- 
ment. If a DECLARE statement contains more than one declaration element, they 
are separated by commas. 

Most of the examples shown previously have only one declaration element in each 
DECLARE statement. In the preceding example, the text CHR BYTE INITIAL ('A') 
is one declaration element; the text COUNT INTEGER is another. 

Another way of combining declaration elements is called a factored declaration as 
indicated above in this section. For example, the non-factored declarations: 

DECLARE A BYTE-, B BYTE, 
DECLARE C WORD-, D WORD; 
DECLARE E DWORD-, F DWORDs 

can be combined as: 

DECLARE ( A -, B ) BYTE, (CnD) WORD n (E-.F) DWORD; 

In each factored declaration, the allocated locations are contiguous. Elements de- 
clared in a nonfactored declaration statement are not necessarily contiguous. 

Variables declared in a factored declaration (i.e., variables within a parenthesized list 
that are not based, are not used as parameters, or are not EXTERNAL), are stored 
contiguously in the order specified. (If a based variable occurs in a parenthesized list, 
the variable is ignored when storage is allocated.) 

The declaration elements in a single DECLARE statement are independent of each 
other, as if they were declared in separate DECLARE statements. 

3.2 Initializations 

Initialization guarantees that the variables being initialized have a particular value 
before program execution begins. Every constant should be initialized. Variables can 
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also be initialized. There are no default values for constants or variables. Of course, 
variables can be initialized by an assignment statement such as the following: 

PI = 3 • lMlSTE? i /* PI must first be declared REAL */ 

VAR13 = lOi /* VAR13 must be declared earlier */ 

However, in PL/M, the compiler can set up these values during the compilation rather 
than using both instruction space and execution time to initialize variables in the 
program. 

There are two kinds of compile-time initializations: INITIAL, used with variables, 
and DATA, used for constants. (DATA is explained in greater detail later in this 
section.) In both initializations, the initialization attribute is placed after the type in 
the declaration. For example: 

DECLARE FAMILY WORD INITIAL (EH 

Additionally, when using a linkage attribute (PUBLIC/EXTERNAL), place the link- 
age attribute after the type declaration and before the initialization attribute. 

INITIAL causes initialization to occur during program loading for variables that have 
storage allocated for them. Such variables can subsequently be changed during exe- 
cution (just as any other variable). These variables will not be reinitialized on a 
program restart. 

The following rules apply to both INITIAL and DATA: 

• INITIAL and DATA cannot be used together in the same declaration. 

• INITIAL can occur only in declarations at the outer level of a module. DATA, 
however, can occur in declarations at any level. 

• No initializations are permitted with based variables (discussed in Section 3.5), 
formal parameters (discussed in Section 8.1.1), or with the EXTERNAL attri- 
bute (discussed in Section 7.2). 

• Either INITIAL or DATA can follow use of the AT attribute (discussed in Section 
3.6). However, if this use of INITIAL or DATA causes multiple initializations, 
the result cannot be predicted. 

• For PL/M-286 and PL/M-386, INITIAL will not initialize pointer (or address) 
types with absolute values. 
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The initializing value should fit into the space allocated by the data type. The 
only exception is initialization of HWORD when the offset is derived with a dot 
operator. For example: 
DECLARE HH HWORD INITIAL (.B) 

In this case, the real offset is truncated to give the lower 16 bits. A warning 
message is issued when an OFFSET value is truncated. 

The general form of the INITIAL attribute is as follows: 
INITIAL lvalue-list) 

Where: 

value-list is a sequence of values separated by commas. 

Values are taken one at a time from the value list and used to initialize the individual 
scalars being declared. The initialization is performed in the same manner as an 
assignment. Initial values for members of an array or structure must be specified 
explicitly. For character string constants, the characters are taken one at a time to 
initialize an 8-bit scalar, two at a time to initialize a 16-bit scalar, four at a time to 
initialize a 32-bit scalar, and eight at a time to initialize a 64-bit scalar. 

For PL/M-86 and PL/M-286, each value can be a string of up to four characters 
(e.g., A', 'NO'), or an expresion with the restrictions noted in the following list. 
(Use byte arrays for longer strings because each element can represent one char- 
acter.) 

The expressions used with the INITIAL attribute have the following restrictions: 

• For real variables only: An expression can only be a single floating-point con- 
stant which can be used to initialize a REAL scalar only. No operator can be used 
with PL/M-86 and PL/M-286, but a unary + or — operator can be used with 
PL/M-386. 

• For POINTER variables only: A restricted expression can be a location refer- 
ence formed with the @ operator, which must refer to a variable already de- 
clared or to a constant list. 

• For all other types (except SELECTOR): A restricted expression can be a con- 
stant expression containing no operators except + or — . A constant expression 
has only whole-number constants as operands (e.g. , 2048, 256 + 5), as explained 
in Chapter 5. The constant expression is evaluated as if it were being assigned to 
the scalar being initialized, using the rules described in Chapter 5. 



PL/M-386 

I 
I 

end 

PL/M-386 
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PL/M-386 

For OFFSET or WORD variables only: A constant expression containing only 
the + and — operators, and operands that can be whole-number constants and/ 
or "." location references. If the expression contains a "." location reference, 
only the + operator can precede it. Any combination of + and — operators can 
follow the " ." location reference. For example: 5 + .xyz - 10. end 

— PL/M-386 



NOTE 

For compatibility with programs written in PL/M-80, PL/M-86/286/386 al- 
lows an expression containing a location reference formed with the dot 
operator. 

The declaration: 

DECLARE THRESHOLD BYTE INITIAL (Hfl)n 

declares the BYTE scalar THRESHOLD and initializes the scalar to a value of 48. 
The declaration: 

DECLARE EVEN (S) BYTE INITIAL (2-, M -, k, -, fl -, 10)i 

declares the BYTE array EVEN and initializes its five scalar elements to 2. 4, 6, 8, 
and 10, respectively. 

The declaration: 

DECLARE COORD STRUCTURE (HIGHSBOUND WORD-, 
VALUE (3) BYTE-, 

L0U5B0UND BYTE) INITIAL (3D2-, 3-, t -, 12-, □ ) =, 

declares the structure COORD and initializes it as follows: 

COORD- HIGHSBOUND to 302 
COORD ■ VALUE ( □ ) to 3 
COORD- VALUE(l) to 6 
COORD • VALUE ( 2 ) to 12 
COORD. LOUSBOUND to 

If a string occurs in the value list, it is taken apart from left to right and the pieces are 
stored in the scalars being initialized. One character is stored in each BYTE scalar, 
two characters in each WORD scalar, and four in each DWORD scalar. For example: 
DECLARE GREETING (S) BYTE AT (S1HI) INITIAL ('HELLO'); 
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causes GREETING(O) to be initialized with the ASCII code for H, GREETINGS ) 
with the ASCII code for E, and so on. 

All the examples shown previously have had value lists that match up one-for-one 
with the scalars being declared. The value list can have fewer elements than are being 
declared. Thus: 

DECLARE DATUM (100) BYTE INITIAL (3-, Si ?i fl)i 

will work. The first four elements of the array DATUM are initialized with the four 
elements in the value list, and the remainder of the array is left uninitialized. How- 
ever, the value list cannot have more elements than are being declared. 

3.2.1 The Implicit Dimension Specifier 

Often, when initializing an array, you want the array to have the same number of 
elements as the value list. This can be done conveniently by using the implicit dimen- 
sion specifier in place of an ordinary dimension specifier (a parenthesized constant). 
The implicit dimension specifier has the form: 
(*) 

Also use the implicit dimension specifier to define an external or based array whose 
precise number of elements is either unknown or insignificant. Thus the declaration: 
DECLARE FAREWELL ( * ) BYTE PUBLIC INITIAL ('GOODBYE-, NOW); 

declares a public BYTE array, FAREWELL, with enough elements to contain the 
string 'GOODBYE, NOW (namely 12), and initializes the array elements with the 
characters of the string. To reference this array in another program module, declare it 
as follows: 

DECLARE FAREUELL ( * ) BYTE EXTERNALS 
See Chapter 7 for more information about PUBLIC and EXTERNAL attributes. 

Note that the INITIAL and DATA value-lists must not be present when the implicit 
dimension specifier is used with an external array; otherwise, INITIAL and DATA 
value-lists are required. Also, the LENGTH, LAST, and SIZE built-ins cannot be 
used on an external array that was declared with the implicit dimension specifier. 

The following is an example of an implicit dimension in a based declaration, which is 
described in Section 3.5: 

DECLARE X BASED P(*) BYTEi 
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The implicit dimension specifier cannot be used after the parenthesized list of identi- 
fiers in a factored declaration (unless it is declared EXTERNAL). Additionally, in 
PL/M-386, an implicit dimension specifier cannot be used to specify an array that is a 
member of a structure. 

The implicit dimension specifier can be used with any value list; it is not restricted to 
strings. 

3.2.2 Names for Execution Constants: the Use of DATA 

A variable is the name of a single data item intended to be used and altered by a 
program. If the variable is not altered during execution, it is a constant. 

For example, the formula for the circumference of a circle (R x 2 x it) or (radius x 2 x 
ir) could be written in PL/M as: 
C = R * 2 ■ □ * 3.mi5Ti 

in which C and R would be variables. The declarations for C and R would have to 
precede the executable statement, and could appear as: 
DECLARE CCi R) REAL=, 

If pi is used often enough, simplify writing of statements by using PI to declare a 
symbolic name with that value as follows: 

DECLARE PI REAL DATA (3.1415157):, 

An array of constants requires a list of values. For example: 

DECLARE FIBONACCI ( 1 ) BYTE DATA ( -, 1 -, 1 , 2 -, 3 , S , A -, 13 , El ) i 

The form and use of the DATA initialization is identical to that of INITIAL except for 
the following differences: 

• DATA causes storage to be allocated in the program's constant data segment. The 
content and meaning of the name cannot be changed during execution. The name 
should never appear on the left-hand side of an assignment statement. (This is 
not the case with INITIAL.) 

• DATA initializations can be used in declarations at any block level in the 
program. (INITIAL can occur only at the module level (i.e., inside the 
DO-block that is the module itself), outside any sub-blocks that the module 
may contain.) 

• If the keyword DATA is used in a PUBLIC declaration when compiling with the 
ROM option (see Section 1 1.2. 19), DATA must also be used in the EXTERNAL 
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declaration of program modules that reference it. However, no value-list can be 
used since the data is defined elsewhere. (INITIAL cannot be combined with 
EXTERNAL.) 

• Use of the AT attribute (as explained in Section 3.6) forces a name to be associ- 
ated with a specific memory location, which can defeat the purpose of the DATA 
initialization. (This will not happen with INITIAL unless the variables and loca- 
tions are explicitly redefined using multiple ATs.) 

• If the first declaration has a data initialization, then the variable that is AT that 
location is also referred to as DATA (i.e., cannot have a value assigned into it). 

3.3 Types of Declaration Statements 

3.3.1 Compilation Constants (Text Substitution): 
The Use of LITERALLY 

If the program is large enough to have many declarations, declaring a compilation 
constant will save time at the keyboard, as follows: 
DECLARE DCL LITERALLY ' DECLARE ' i 

Thereafter, during compilation, every time DCL appears alone (not as part of a 
word), the full string DECLARE will be substituted by the compiler. Subsequent 
declarations can be written as follows: 

DCL AREA REAL=, 
DCL SIZE WORDn 

A declaration using the reserved word LITERALLY defines a parameterless macro 
for expansion at compile-time. Declare an identifier to represent a character string, 
which will then be substituted for each occurrence of the identifier in subsequent text. 
This expansion will not take place in strings or constants. The form of the declara- 
tion is: 

DECLARE identifier LITERALLY 'string'--, 

Where: 

identi f ier is any valid PL/M identifier. 

string is a sequence of arbitrary characters (limited by the size of the 

symbol table) from the PL/M set (except an apostrophe). 

An apostrophe can be included in a string by writing it as two consecutive apos- 
trophes. 
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The following example illustrates another use of LITERALLY: 

DECLARE TRUE LITERALLY ' DFFH ' -, FALSE LITERALLY 'O'n 

DECLARE ROUGH BYTE i 

DECLARE (X-, Y -, DELTA-, FINAL) REAL"-, 

ROUGH = TRUEn 
DO WHILE ROUGH--, 

X = SMOOTH (X-, Y-, DELTA) "-, 

/* SMOOTH is a procedure declared elsewhere- */ 
IF (X-FINAL) < DELTA THEN 
ROUGH = FALSER 

END i 

This example of a LITERALLY declaration defines the Boolean values TRUE and 
FALSE in a manner consistent with the way PL/M handles relational operators (see 
Chapter 5). Literal substitution for fixed values makes a program more readable. 

LITERALLYs can also be used to declare quantities that are fixed for one compila- 
tion, but are subject to change from one compilation to the next. Consider the follow- 
ing example: 

DECLARE BUFFERSSIZE LITERALLY '3S'% 
DECLARE PRINT$BUFFER(BUFFER$SIZE) WORD; 

PRINT$BUFFER(BUFFER$SIZE - ID) = ' G ' i 

A future change to BUFFER$SIZE can be made in one place, at the first declaration, 
and the compiler will propagate the change throughout the program during compila- 
tion. This eliminates the need to search the program for the occurrences of 32 that are 
BUFFER$SIZE references and not some other reference to 32. 

3.3.2 Declarations of Names for Labels 

A label marks the location of an instruction. Labels are permitted only on executable 
statements, not on declarations. 
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A name can be declared as a label both explicitly and implicitly. Explicit label decla- 
rations are used mainly to enable module-to-module references (see Chapter 7). The 
three explicit label declarations have the following formats: 

• DECLARE PART3 LABELS 

• DECLARE START1 LABEL PUBLIC; /* for intermodule reference */ 

• DECLARE PHASES LABEL EXTERNAL; /* for intermodule reference */ 

The rules for explicit label declarations are discussed in detail in Chapter 7. 

In implicit label declarations (used more commonly than explicit label declarations), 
the name is placed at the very beginning of the executable statement to which the 
name is supposed to point. For example: 

STARTS: ALPHA = 127=, 

This statement defines the label START2 as pointing to the location of the PL/M 
instruction shown. If this block has no explicit declaration of START2, such as the 
following: 

DECLARE STARTS LABEL; 

then the compiler takes the definition of START2 as an implicit declaration as well as 
a definition, as if the declaration had occurred at the start of the last simple DO or 
procedure statement. (If there is an explicit declaration, then the actual placement of 
the label remains simply a definition.) 

Labels are used to indicate significant instructions or the starting point of instruction 
sequences. Labels can be useful reference points for understanding the parts of a 
program, or targets for the transfer of control during execution (as discussed under 
GOTO and CALL in Chapter 6). 

3.3.3 Results of Label Declarations 

Valid label declarations result in the following: 

• The declared name can be used to point to an executable instruction. 

• The use of the declared name as a variable in its block is disallowed. 

• If the label is also defined in its block by appearing in an executable statement, 
the address of that statement will be assigned as the value of the label. 
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3.3.4 Declaration for Procedures 



To declare a procedure, give its name with a statement of the form: 
name: PROCEDURE 

followed optionally by parameters, type and/or attributes. The definition of the proce- 
dure then follows. The procedure definition is the set of statements declaring items 
used in the procedure (including any parameters) and the executable statements of the 
procedure itself. The definition ends with an END statement, optionally including the 
procedure name. 

The complete declaration of a procedure includes all the statements from the 
PROCEDURE statement through the END statement. This definition/declaration 
must appear before the procedure name is used in an executable statement, just as 
variable and constant names must be declared before their use. 

The only exceptions arise when the full definition may appear in another separately 
compiled module where it is declared PUBLIC, or when a procedure has been de- 
clared REENTRANT. A PUBLIC procedure can be used (called) only if the calling 
module meets the following requirements: 

1 . The procedure has been declared with the EXTERNAL attribute (so the linker or 
binder will search for it). 

2. Each formal parameter the procedure uses has been declared so the compiler can 
verify correct usage when this module invokes the procedure. End this local 
declaration with an END statement. 

For example: 

SUrlrlER: PROCEDURE (An B) EXTERNAL i 

declare a word-, b byte i 
end summer:, 

See Chapter 7 for details on intermodule references. See Chapter 8 for details on 
procedure definition and use. 

3.4 Data Types 

Data types apply not only to variables, but to every value processed by a PL/M 
program. This includes values returned by procedures as well as values calculated by 
processing expressions. Data type specifications determine the value an object can 
have, how this value is stored in memory, and the operations that can be used on the 
value. 
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The PL/M compilers recognize five classes of data, each of which has one or more 
data types. 

There are several unsigned binary number types: BYTE (8-bit number), WORD (16- 
bit number in PL/M-86 and PL/M-286; 32-bit number in PL/M-386), HWORD 
(PL/M-386 only; same as PL/M-86/286 WORD); and DWORD (32-bit number in 
PL/M-86/286; 64-bit number in PL/M-386). The OFFSET type (PL/M-386 only) is 
a 32-bit number that representes the offset portion of a pointer, which has its own 
type: POINTER. (The POINTER type itself is recognized by PL/M-86 and -286, as 
well as by PL/M-386.) Note that the compiler controls WORD32 and WORD16 
automate mapping 32- and 16-bit types. These controls are discussed in Chapter 1 1 . 

There are four signed integer data types: INTEGER (16-bit number in PL/M-86 and 
PL/M-286; 32-bit number in PL/M-386); CHARINT (PL/M-386 only; an 8-bit num- 
ber); SHORTINT (PL/M-386 only; same as PL/M-86/286 INTEGER type). 

PL/M-86, -286 and -386 all recognize the floating-point data type REAL, for signed 
32-bit numbers. 

The data types differ from one microprocessor to the other. Throughout this manual, 
the data types are referenced according to the data type class. Table 3-2 summarizes 
the data type classes for the 8086, 80286 and 80386 microprocessors. The PL/M-386 
data types are defined for WORD32. See Section 3.7 for a discussion on the PL/M- 
386 compiler's WORD32/WORD16 mapping. 

Although the PL/M-386 compiler assumes a 32-bit word, the PL/M-386 compiler 
accepts PL/M-286 code as input. PL/M-286 code can take advantage of the 32-bit 
data type provided by the 80386 microprocessor when compiled with the PL/M-386 
compiler. 
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Table 3-2 Data Types 





Data Type and Value 


Microprocessor 


Unsigned 
Binary 
Number 


Description 


8086/80286/80386 


BYTE 


8-bit number ranging from to 255. Occu- 
pies one byte of memory. 


8086/80286 


WORD 


16-bit number ranging from to 65,535. 


80386 


HWORD 


Occupies two contiguous bytes of memory. 
The least significant 8 bits are stored in the 
lower address. 


80386 


WORD 


32-bit number ranging from to 
4,294,967,295. Occupies two contiguous 
HWORDs of memory. The least significant 
16 bits are stored in the lower address. 


8086/80286 


DWORD 


32-bit number ranging from to 
4,294,967,295. Occupies two contiguous 
WORDs of memory. The least significant 
16 bits are stored in the lower address. 


80386 


DWORD 


64-bit number ranging from to (2**64) 
-1. Occupies two contiguous WORDs of 
memory. The least significant 32 bits are 
stored in the lower address. 


80386 


OFFSET 


32-bit number that represents the offset 

ported by PL/M-80 and PL/M-86/286) is 
equivalent to OFFSET. 


Microprocessor 


Signed 
Integers 


Description 


8086/80286 


INTEGER 


16-bit number ranging from -32768 to 


80386 


SHORTINT 


+ 32767. Occupies two contiguous bytes 
of memory. The least significant 8 bits are 
stored in the low address. Internally stored 
in two's complement notation. 
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Table 3-2 Data Types (continued) 



Microprocessor 


Signed 
Integers 


Description 


80386 


INTEGER 
CHARINT 

w i inni i 'i i 


32-bit number ranging from 
-2,147,483,648 to +2,147,483,647. Oc- 
cupies four contiguous bytes of memory. 
The least significant 16 bits are stored in 
the low address. Internally stored in two's 
complement notation. WORD32's 
I ONGINT is pnuivalent to INTEGER (see 
Section 3.7). 

ft-hit numhpr ranninn frnnn — 1 PR tn -4- 1 P"7 

uil 1 1 u 1 1 1 uci i cu i y i h y 1 1 kj i i i ■ <—\J wj ~ \ c. i . 

Occupies one byte of memory. Internally 
stored in two's complement notation. 


Microprocessor 


Real 
Numbers 


Description 


8086/80286/80386 


REAL 


Signed, floating-point number. Occupies 
four contiguous bytes of memory. 


Microprocessor 


Pointers 


Description 


8086/80286/80386 


POINTER 


The value is the address of the memory 
storage location. Consists of a segment 
selector portion and an offset portion. 


Microprocessor 


Selectors 


Description 


8086/80286/80386 


SELECTOR 


The value is equivalent to the segment se- 
lector portion of a POINTER. Can be used 
as the base of a based variable. 
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3.4.1 Unsigned Binary Number Variables: Unsigned Arithmetic 



Unsigned arithmetic is used to perform any arithmetic operation on unsigned binary 
number variables. All of the PL/M operators can be used with these data types. 
Arithmetic and logical operations on such variables yield a result of one of the un- 
signed binary number types, depending on the operation and the operands. Relational 
operations always yield a true or false result of type BYTE. 

With unsigned arithmetic, if a large value is subtracted from a smaller one, the result 
is the two's complement of the absolute difference between the two values. For exam- 
ple, if a BYTE value of 1 (00000001 binary) is subtracted from a BYTE value of 
(00000000 binary), the result is a BYTE value of 255 (1 1 1 1 1 1 1 1 binary). 

Also, the result of a division operation is always truncated (rounded down) to a whole 
number. For example, if a PL/M-86/286 WORD (or PL/M-386 HWORD) value of 7 
(00000000000001 1 1 binary) is divided by a BYTE value of 2 (00000010 binary), the 
result is a PL/M-86/286 WORD (or PL/M-386 HWORD) value of 3 
(0000000000000011 binary). 

When declaring a variable that may be used to hold or produce a negative result, it is 
advisable to make the variable either a signed integer or real. If the variable is sup- 
posed to hold or produce a non-integer, it must be declared as REAL. Use of the 
appropriate data types will reduce the occurrences of incorrect results from arithme- 
tic operations (see Chapter 5). 

3.4.2 INTEGER Variables: Signed Arithmetic 

The sign bit is if the INTEGER value is positive or zero, and 1 if the value is 
negative. The magnitude is given in two's complement notation. 

3.4.2.1 Signed Arithmetic 

For the 8086 and the 80286 microprocessors, arithmetic operations on INTEGER 
variables use 16-bit signed integer arithmetic to hold signed intermediate or final 
results. For the 80386 microprocessor, arithmetic operations on signed variables use 
32-bit signed arithmetic to hold signed intermediate or final results. Thus, addition 
and subtraction always produce mathematically correct results if overflow does not 
occur. (See also the OVERFLOW control in Chapter 11.) Relational operations are 
signed arithmetic comparisons that yield a true or false result of type BYTE. 
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However, as with unsigned binary number operands, division produces only an 
INTEGER result. The result is rounded toward zero (i.e., down if the result is posi- 
tive, up if the result is negative). 

Only the arithmetic and relational operators can be used with signed operands. Logi- 
cal operators are not allowed except for constant expressions within cast parentheses 
(see Chapter 5). 

3.4.3 REAL Variables: Floating-Point Arithmetic 

The value of a REAL variable is a signed floating-point number that occupies four 
contiguous bytes of memory, which may be viewed as 32 contiguous bits in the single 
precision format. The bits are divided into fields as follows: 



SIGN EXPONENT 



SIGNIFICAND 



31 30 23 22 

The byte with the lowest address contains the least significant 8 bits of the signifi- 
cand, and the byte with the highest address contains the sign bit and the most 
significant 7 bits of the exponent field. 

The sign bit is if the REAL value is positive or zero, and 1 if the REAL value is 
negative. 

The exponent field contains a value offset by 127. In other words, the actual exponent 
can be obtained from the exponent field value by subtracting 127. This field is all 0s 
if the REAL value is zero. 

The significand contains the binary digits of the fractional part of the REAL value 
when this part is represented in binary scientific notation. This field is all 0s if the 
REAL value is zero. 

Operations on REAL operands use signed floating-point arithmetic to yield a result 
of type REAL. The implementation guarantees that the result of each operation is the 
closest floating-point number to the mathematical real-number result (if overflow or 
underflow does not occur). The relational operators and the arithmetic operators + , 
— , *, and / can be used with REAL operands: the MOD operator and the logical 
operators are not allowed. Arithmetic operations yield a result of type REAL and 
relational operations yield a true or false result of type BYTE. 

The PL/M compiler extends the utility of the REAL data types by holding intermedi- 
ate results in the numeric coprocessor's temporary-real format (80-bit). This format 
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preserves 64 bits of precision and the full range of representable numbers. The expo- 
nent in this format is 15 bits instead of 8 in the single precision format. 

The increased exponent range greatly reduces the likelihood of underflow and over- 
flow, and eliminates roundoff as a source of error until the final assignment of the 
result is performed. Underflow, overflow, and roundoff errors are probable for inter- 
mediate computations as well as in the final result. For example, an intermediate 
underflow result might later be multiplied by a very large factor, providing a final 
result of acceptable magnitude. 

3.4.4 Examples of Binary Scientific Notation 

1 . Consider the following binary number (which is equivalent to the decimal value 
10.25): 

1010.01B 

The dot (.) in this number is a binary point. The same number can be repre- 
sented as: 

1.01001B *2**3 

This is binary scientific notation, with the binary point immediately to the right 
of the most significant digit. The digits 01001 are the fractional part, and 3 is the 
exponent. This value would be represented in the single precision format as 
follows: 

• The sign bit would be 0, because the value is positive. 

• The exponent field would contain the binary equivalent of 127 + 3 = 130. 

• The leftmost digits of the fraction field would be 01001 , and the remainder of 
this field would be all 0s. 

The complete 32-bit representation would be: 
□ 1DDDDD1D 01001000QD000QDDQQ000D0 

and the contents of the four contiguous memory bytes would be as follows: 

highest address : 01000001 

00100100 

00000000 
lowest address: 00000000 

Note that the most significant digit is not actually represented, because by 
definition it is a 1 unless the REAL value is zero. If the REAL value is zero, 
the entire 32-bit representation is all 0s. 
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2. Consider the fraction 1/16, or 0.0625. In binary, it is: 
1 ■ □□□OB * 2**(-L() 

In single precision format, the actual exponent —4 would be represented as 123 
(127 —4), and the fraction field would contain all 0s. 

In the single precision format, the largest possible value for a valid exponent 
field is 254, which corresponds to an actual exponent of 127. Therefore, the 
largest possible absolute value for a positive or negative REAL value is: 

1.11111111111111111111111B * 5**127 

or approximately 3.37 * 10**38. 

The lowest permissible exponent field value for a non-zero REAL value is 1, 
which corresponds to an actual exponent of — 126. Therefore, the smallest pos- 
sible absolute value for a positive or negative REAL value is: 
l.rjB * 2**(-12b) 

or approximately 8.43 * 10**(-37). 



3.4.5 POINTER Variables and Location References 

The value of a POINTER variable is the address of the microprocessor's storage 
location and consists of a segment selector portion (see Chapter 9) and an offset 
portion. 

PL/M-86 — 

For the 8086 microprocessor, the bits are divided as follows: 

SEGMENT OFFSET 
31 16 15 

end 

PL/M-86 — 
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For the 80286 microprocessor, the bits are divided as follows: 
i SELECTOR 1 



PL/M-286 

I 



INDEX 


Tl 


RPL 


OFFSET 


31 




19 


16 


15 








I 



end 

PL/M-286 



PL/M-386 



For the 80386 microprocessor, the bits are divided as follows: 
i SELECTOR ! 



INDEX 


Tl 


RPL 

i 


OFFSET 


47 


34 


33 


31 








end 

PL/M-386 

POINTER variables are important as bases for based variables (see Section 3.5). 

Only the relational operators for equality and inequality ( = or < > ) can be used 
with POINTER operands, yielding a true or false result of type BYTE. No arithmetic 
or logical operations are allowed (see Chapter 5). 

In PL/M-386, a POINTER can be viewed as a structure of SELECTOR and OFFSET 
rather than a scalar. Therefore, arithmetic with POINTERS (e.g., FTR + 1) is illegal. 

The value of a POINTER variable can be created or changed in the following ways: 

• The variable can be initialized when declared, using INITIAL or DATA with an 
address created with @ . 

• For PL/M-86, the variable can be assigned a whole-number constant (see Chap- 
ter 5). 

• The variable can be assigned an address created via the @ operator (described in 
the following section). This is the most commonly used method. 

• The variable can be assigned the value of a POINTER variable or function 
(including NIL, described in Chapter 9). 
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• The variable can be assigned a value generated by the BUILD$PTR function 
(also described in Chapter 9). 

• POINTER type conversion (cast). Changing from one value to another is differ- 
ent from the POINTER built-in function (see Chapter 9). 

• In SMALL RAM model, the POINTER is actually the offset portion only. In this 
case, all operations on the PL/M-386 OFFSET data type can be used, including 
arithmetic. 

3.4.5.1 The @ Operator 

A location reference is formed with the @ operator. A location reference has a value 
of type POINTER, that is, a location address. An important use of location refer- 
ences is to supply values for POINTER variables. 

The basic form of a location reference is as follows: 
@ variable-ref 

Where: 

variable-ref is the name of a variable. 

The value of this location reference is the actual run-time location of the variable. 

The variable-ref may also refer to an unqualified array or structure name. The 
pointer value is the location of the first element or member of the array or structure. 

Consider the following declarations: 

DECLARE RESULT REAL i 

DECLARE XNUM(IDO) BYTE i 

DECLARE RECORD STRUCTURE (KEY BYTE-, 

INF0(25) BYTE-, 

HEAD POINTER) =, 
DECLARE LIST ( IBS ) STRUCTURE (KEY BYTE-, 

INF0(2S) BYTE-, 

HEAD POINTERS 

The ©RESULT is the location of the REAL scalar RESULT, and @XNUM(5) is the 
location of the 6th element of the array XNUM. @XNUM is the location of the 
beginning of the array, that is, the location of the first element (element 0). 

The RECORD STRUCTURE declares a byte called KEY followed by 25 bytes called 
INFO(0), INFO(l), and so on, followed by the POINTER variable named HEAD. 
Because KEY, INFO, and HEAD are all declared part of the RECORD structure, 
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their contents must be referred to as RECORD. KEY. RECORD. INFO(O), 
RECORD.INFO(24), and RECORD.HEAD. 

Refer to the addresses of these elements of the RECORD structure by using the @ 
operator. ©RECORD.HEAD is the location of the POINTER scalar RECORD. 
HEAD and ©RECORD is the location of the structure, which is the same as that of 
the BYTE scalar RECORDKEY ©RECORDINFO is the location of the first ele- 
ment of the 25-byte array RECORD. INFO, whereas @ RECORD. INFO(7) is the 
location of the 8th element of the same array. 

LIST is an array of structures. The location reference @LIST(5).KEY is the location 
of the scalar LIST(5).KEY. Note that @ LIST. KEY is illegal because it does not 
identify a unique location (i.e., the KEY of which LIST). 

The location reference @LIST(0).INFO(6) is the location of the scalar LIST(O). 
INFO(6). Also, @LIST(0).INFO is the location of the first element of the same array 
(i.e., the location of the array itself). 

A special case exists when the identifier used as variable-ref is the name of a proce- 
dure. This procedure must be declared at the outer level of the program module. No 
actual parameters can be given (even if the procedure declaration includes formal 
parameters). The value of the location reference in this case is the location of the 
entry point of the procedure. (Further discussion of procedures is in Chapter 8 and 
Appendixes F and G.) 

3.4.5.2 Storing Strings and Constants via Location References 

Another form of location reference is the following: 
©(constant list) 

Where: 

constant list is a sequence of one or more BYTE constants separated by com- 
mas and enclosed by parentheses. 

When this type of location reference is made, space is allocated for the constants. The 
constants are stored in this space (contiguously, in the order given by the list), and the 
value of the location reference is the location of the first constant. If RAM is speci- 
fied on the compiler invocation command, constants are stored in the DATA segment. 
If ROM is specified on the compiler invocation command, constants are placed in the 
CODE segment (see Chapters 1 1 and 13). 

Values in the constant list are treated as if they were in a BYTE array initialization 
list. 
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Strings can be included in the list. For example, if the operand: 
3 ( 'NEXT VALUE*) 

appears in an expression, it causes the string 'NEXT VALUE' to be stored in memory 
(one character per byte, thus occupying 10 contiguous bytes of storage). The value of 
the operand is the location of the first of these bytes; in other words, it is a pointer to 
the string. 



3.4.6 OFFSET Data Type and the Dot Operator 

A dot operator is provided for compatibility with PL/M-80 programs. The dot opera- 
tor (.) is similar to the @ operator, but produces an address of type WORD. This 
address represents an offset in the current data segment (for variables) or in the 
current code segment (for procedures). Use this address with caution, because it can 
produce unexpected results in a PL/M program that contains more than one data 
segment or more than one code segment. 

In a PL/M-386 program, wherever WORD can be used, OFFSET can also be used. 
The main difference between the two types is in casting. 

To create or change the value of an OFFSET variable, it can be assigned an OFFSET 
variable or function, or assigned the result of the built-in function OFFSET$OF, or 
OFFSET type conversion, or the dot operator (see Chapter 9). 



3.4.7 SELECTOR Variables 

The value of a SELECTOR variable is equivalent to the segment selector portion of a 
POINTER, and can also be used as the base of a based variable (see Section 3.5). 

PL/M-86 — 

In the PL/M-86, the bits of the SELECTOR portion of a POINTER are as follows: 



SEGMENT 

31 16 



end 

PL/M-86 
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PL/M-286/386 

I 



In PL/M-286 and PL/M-386, the bits of the SELECTOR portion of a POINTER are 
as follows: 



INDEX 


Tl 


RPL 


31 


-PL/M-286- 


18 


16 


47 


-PL/M-386- 


34 


32 



PL/M-286/386 



The sections of this diagram are discussed in detail in Chapter 10. 

Only the logical and relational operators for equality and inequality ( = , < , > and 
< >) can be used with SELECTOR operands, yielding a true or false result of type 
BYTE. No arithmetic operations are allowed (see Chapter 5). 

To create or change the value of a SELECTOR variable it can be assigned a 
SELECTOR variable or function, or assigned the result of the built-in function 
SELECTOR$OF or SELECTOR type conversion (see Chapter 9). 

The results of the @ and dot operators cannot be assigned directly to SELECTOR 
variables. They must first be converted to SELECTOR type with the built-in func- 
tions SELECTOR$OF and SELECTOR. 



3.5 Based Variables 

Sometimes, the address of a variable is not known until the program is actually run. 
For instance, if a procedure is written to swap two bytes and this procedure is called 
from various places in the code, the addresses of the two bytes are not known when 
writing the procedure definition. 

For this type of manipulation, PL/M uses based variables. A based variable is one 
that is pointed to by another variable called its base. This means the base contains the 
address of the desired (based) variable. A variable is made BASED by inserting in its 
declaration the word BASED and the identifier of the base (which must already have 
been declared). 
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A based variable is not allocated storage by the compiler. At different times during 
program execution the based variable may actually refer to different places in mem- 
ory, because the variable's base may be changed by the program. 

To declare an address based variable, first declare its base, which must be of type 
POINTER, SELECTOR, or WORD. (Additionally, in PL/M-386, the base can be of 
type OFFSET.) Next, declare the based variable itself as follows: 

DECLARE I BYTE n 

DECLARE ITEN$PTR POINTER i 

DECLARE ITEI1 BASED ITEMSPTR BYTE i 

In these declarations, a reference to ITEM is, in effect, a reference to the BYTE value 
pointed to by the current value of ITEM$PTR. Thus, the sequence: 

ITEMSPTR = Sin 
ITEfl = 77Hi 

loads the BYTE value of 77 (hex) into the variable I. 

PL/M supports more than one level of based variable, so variables can be based on 
based variables. 

For example, the following declarations are valid: 

DECLARE PTR1 POINTER i 

DECLARE PTR5 BASED PTR1 POINTER n 

DECLARE STR1 BASED PTR2 STRUCTURE ( 

X REAL-, 

Y READ", 

The following restrictions apply to bases: 

• The base must be of type POINTER, SELECTOR, or WORD (and in PL/M- 
386, OFFSET). However, use a base of type OFFSET or WORD with caution 
because it does not contain a full microprocessor address. OFFSET- or WORD- 
based variables are addressed relative to the current DS register. 

• The base cannot be subscripted. That is, it cannot be an array element. 

The word BASED must immediately follow the name of the based variable in its 
declaration, as in the following examples: 

DECLARE (AGESPTR-i INCOKESPTR-, RATINGSPTR-, CATEG0RY5PTR) POINTER i 
DECLARE AGE BASED AGESPTR BYTE^ 

DECLARE ( INCOME BASED INCOI1E$PTR-i RATING BASED RATING5PTR) UORDi 
DECLARE (CATEGORY BASED CATEG0RY5PTR ) (10D) WORD; 
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In the first DECLARE statement, the POINTER variables AGE$PTR, INCOME 
$PTR, RATING$PTR, and CATEGORY$PTR are declared. They are used as bases 
in the next three DECLARE statements. 

In the second DECLARE statement, a BYTE variable called AGE is declared. The 
declaration implies that whenever AGE is referenced by the running program, its 
value will be found at the location given by the current value of the POINTER vari- 
able AGE$FTR. 

The third DECLARE statement declares two based variables, both of type WORD. 

The fourth DECLARE statement defines a 100-element WORD array called 
CATEGORY, based on CATEGORY$PTR. When any element of CATEGORY is 
referenced at run time, the current value of CATEGORY$PTR is the location of the 
array CATEGORY (i.e., its first element). 

The other elements follow contiguously. The parentheses around the tokens 
CATEGORY BASED CATEGORY$PTR make the statement more readable, but are 
not required. 

3.5.1 Location References and Based Variables 

An important use of location references is to supply values for bases. Thus, the @ 
operator, together with the based variable concept, gives PL/M a very powerful facil- 
ity for manipulating pointers. 

For example, to refer to the three different REAL variables: NORTH$ERROR, 
EAST$ERROR, and HEIGHT$ERROR at different times with the single identifier 
ERROR, write: 

DECLARE (NORTHSERROR-, EASTSERROR-, HEIGHT$ERROR ) REAL 1 -, 

DECLARE ERR0R5PTR POINTER i 

DECLARE ERROR BASED ERR0R5PTR RE AL i 

ERR0R5PTR = SINORTH^ERROR '-, 

The value of ERROR$PTR is the location of NORTH$ERROR. A reference to 
ERROR is, in effect, a reference to NORTH$ERROR. Later in the program, write: 
ERRORSPTR = 5)HEIGHT^ERR0R 

Now a reference to ERROR is, in effect, a reference to HEIGHT$ERROR. In the 
same way, the value of the pointer can be made the location of EAST$ERROR, and a 
reference to ERROR can be made a reference to EAST$ERROR. 
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This technique is useful for manipulating complicated data structures and for passing 
locations to procedures as parameters. Examples are given in Chapter 8. 



3.6 The AT Attribute 

The AT attribute causes the address of a variable to be the specified location. The AT 
attribute has the form: 

AT (location) 
Where: 

location must be a location reference formed with the @ operator (or, in 
PL/M-86, a whole-number constant in the range to 1,048,575). 

AT must refer to a nonbased variable that has already been declared. If there is a 
subscript expression, it must be a constant expression containing no operators except 
+ and - . 

The following are examples of valid AT attributes: 

AT OBUFFER) 

AT ( 5IBUFFER ( 12A ) ) 

AT ( SNAKES ( INDEX + 1) ) 

In the last example, INDEX represents a whole-number constant that has been previ- 
ously declared with a LITERALLY declaration. The compiler replaces this name 
with the declared whole-number constant, thus satisfying the restrictions previously 
mentioned. 

PL/M-86/286 — 

NOTE 

For compatibility with programs written in PL/M-80, PL/M-86 and PL/M-286 

allow the location in an AT attribute to be an expression containing a location 

reference formed with the dot operator, 
end 

PL/M-86/286 — 

The first nonbased variable in a factored declaration containing the AT attribute will 
have the address specified by location. Other variables in the same declaration will, 
in sequence, refer to successive locations thereafter. 

For example, the declaration: 

DECLARE (CHARSA-, CHAR$B. CHARSO BYTE AT ( 3BUFFER ) '-, 
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causes the BYTE variable CHAR$A to refer to the location of BUFFER. The vari- 
ables CHAR$B and CHAR$C are located in the next two bytes after CHAR$A. 



The declaration: 

DECLARE TCLD) STRUCTURE (X(3) BYTE n 

Y(3) BYTE-, 

Z(3) BYTE) AT ( 3D AT A5BUFFER ) "-, 

sets up structure references to 90 bytes. They are organized so that each of the 10 
members of T refers to nine bytes. The first three use the name X, the second three Y, 
and the last three Z. Figure 3-1 illustrates this structure. 

The preceding declaration, using the AT attribute, causes the beginning of the struc- 
ture T, namely the scalar T(0).X(0), to be located at the same location as a previously 
declared variable called DATA$BUFFER. The other scalars making up the structure 
will follow this location in logical order: T(0).X(1), T(0).X(2), and so on up to 
T(9).Z(2), which is the last scalar, located in the 89th byte after the location of 
DATA$BUFFER. 

However, no memory locations for these 90 scalars are allocated by this declaration. 
You determine the contents of the memory space beginning at @DATA$BUFFER. 



Tioi.xm 

TiO).Y(O) 
T(0|.Y(2> 
TIO) Z(1) 
Til) X(0) 
TOI.XIJI 
WCWI 



TIOI.XIO) 
T(0).XI2) 
T(Q).Vtl) 
TIO) ZIOI 
TI0I.ZI2) 
TI1) XII) 
TID.YIO) 



Figure 3-1 Successive Byte References of a Structure 
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The following rules apply to the AT attribute: 

• AT cannot be used with variables that are based, EXTERNAL, or parameters. 

• AT can be used with the PUBLIC attribute, if it immediately follows the word 
PUBLIC. However, the location cannot be a location reference to a variable that 
is EXTERNAL. 

The AT attribute can be used to make variables equivalent, providing more than one 
way of referring to the same information. For example: 

DECLARE DATUM UORDn 

DECLARE ITEM BYTE AT ( 9DATUH ) i , 

causes ITEM to be declared a BYTE variable at the same location that has just been 
allocated for the WORD variable DATUM. (For the 80386 microprocessor, the pre- 
ceding example would use HWORD instead of WORD.) Thus, any reference to 
ITEM is, in effect, a reference to the low-order byte of DATUM (because WORD (or 
HWORD) values are stored with the low-order 8 bits preceding the high-order 8 bits). 

The following is another example using the AT attribute: 
DECLARE VECTOR (b) BYTEn 

DECLARE SH0RT5VECT0R STRUCTURE (FIRST (3) BYTE-, 

SECOND (3) BYTE) 
AT ( 3VECT0R ) '-, 

In this example, a six-element BYTE array called VECTOR is declared. Addition- 
ally, a structure of two three-BYTE arrays, SHORT$VECTOR. FIRST and SHORT- 
$VECTOR.SECOND is declared. 

The first scalar of this structure, SHORT$VECTOR.FIRST(0), is located at the same 
location as the first element of the array VECTOR. 

Thus, there are two ways to refer to the same six bytes. For example, the fifth byte in 
the group can be referenced as either VECTOR(4) or SHORT$ VECTOR. 
SECOND(l). 

When a variable is declared with the AT attribute, the compiler does not optimize the 
machine code generated to access that variable. 
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3.7 WORD32/WORD16 Type Mapping 

The PL/M-386 compiler supports two primary controls, WORD32 and WORD 16, 
for unsigned binary number and signed integer data types, which provide some basic 
data type and language semantics compatibility for the 80[x]86 family of micropro- 
cessors. These controls specify the basic WORD size and thus affect the representa- 
tion of certain data types. The default for PL/M-386 is WORD32. This differs from 
existing 16-bit PL/M-86 and PL/M-286 source code in which the word size is 16 bits. 
The WORD16 control does not specify 80286 code (e.g., a parameter pushed to the 
stack is still four bytes), but maps the names of some data types into others. Internally 
all processing is the same (e.g., signed arithmetic is 32-bit for both WORD 16 and 
WORD32). To accommodate existing 16-bit code where data type representation is 
critical, WORD 16 can be used to map word size to the convention used in PL/M-86 
and PL/-286. Table 3-3 lists the data type representation for WORD32 and 
WORD 16. 



Table 3-3 WORD32/WORD16 Type Mapping 



Unsigned Binary Number 
Data Types 


WORD32 (default) 


WORD16 


BYTE 


8-bit 


8-bit 


HWORD 


16-bit 


8-bit 


WORD 


32-bit 


16-bit 


DWORD 


64-bit 


32-bit 


QWORD 


64-bit 


64-bit 


Signed Integer 
Data Types 


WORD32 


WORD16 


CHARINT 


8-bit 


8-bit 


SHORTINT 


16-bit 


8-bit 


INTEGER 


32-bit 


16-bit 


LONGINT 


32-bit 


32-bit 
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NOTE 

The PL/M-286 ADDRESS data type is equivalent to WORD. In PL/M-386, 
ADDRESS is equivalent to the OFFSET data type. OFFSET is a 32-bit data 
type that represents the offset portion of a POINTER. The size of OFFSET is 
not affected by the WORD32/WORD16 compiler control. 

When writing new PL/M code, or when updating existing PL/M code, it is best 
to declare variables used for local addressing (i.e., those that are assigned from 
or initialized to the dot operator (.) location references, assigned from the OFF- 
SET$OF function, or used with the BUILDSPTR function or the STACK$PTR 
built-in) as OFFSET (or ADDRESS). If the code is compiled using a version of 
PL/M-86 or PL/M-286 where the OFFSET data type is not part of the lan- 
guage, OFFSET can be declared LITERALLY 'ADDRESS'. 

In PL/M-386, WORD is the natural 32-bit data type of the language on which 
all operations are available. However, in ASM386 a WORD is 16 bits and a 
DWORD is 32 bits. 



3.8 Choosing WORD32 or WORD16 

The WORD32/WORD16 compiler control enables determination of how the data 
type mapping in the source code is interpreted by the PL/M-386 compiler. See Chap- 
ter 1 1 for a description of the WORD32/WORD16 control and syntax. 

When compiling new PL/M-386 source code, use WORD32 to take full advantage of 
the 80386 features. 

When recompiling existing PL/M-86 or PL/M-286 code, consider the source code to 
determine which compiler control to use. WORD32 is usually preferable. Use 
WORD 16 if one of the following conditions apply to the source code: 

• Scalar types are mapped to external data, such as STRUCTURES defined to 
represent data records read from a peripheral device. The format of the data 
from the peripheral device will not change even though the 80386 microproces- 
sor is processing the data instead of the 8086 or 80286 microprocessors. 

• Data is overlaid, for example in a PL/M-286 program: 
DECLARE W WORD (Bl ,B2) BYTE AT (@W); 

DECLARE P POINTER, B BASED P (2) BYTE, WW BASED P WORD; 
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PL/M-386 

(continued) 

In the preceding example, code may depend on the fact that two BYTES overlaying l 
the WORD constitute both halves of the WORD completely. Similarly, code can de- 
pend on the fact that the LOW or HIGH of a WORD returns 8 bits. 

• Loops depend on the size of a WORD type. Operations dependent on a variable 
overflow could produce unexpected results. 

end 

— PL/M-386 
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4.1 Arrays 



For increased efficiency, it is often desirable to use a single identifier to refer to a 
whole group of scalars, and to distinguish the individual scalars by means of a sub- 
script (i.e., a value enclosed in parentheses). Such a list, in which the scalars are all 
the same type, is called an array. 

An array is declared by using a dimension specifier. The dimension specifier is a 
nonzero whole-number constant enclosed in parentheses. The value of the constant 
specifies the number of array elements (individual scalar variables) making up the 
array. For example: 

DECLARE ITEMS (100) BYTE"-, 

causes the identifier ITEMS to be associated with 100 array elements, each of type 
BYTE. One byte of storage is allocated for each of these scalars. 



The elements of an array are stored contiguously, with the first element in the lowest 
location and the last element in the highest location. No storage is allocated for a 
based array, but the elements are considered to be contiguous in memory. 

The declaration: 

DECLARE (WIDTH-, LENGTH-, HEIGHT) (100) REAL; 

is similar to the following sequence: 

DECLARE WIDTH (100) REAL; 
DECLARE LENGTH (100) REAL; 
DECLARE HEIGHT (100) REAL; 

The difference between the two declarations is that contiguous storage is guaranteed 
for variables declared in a single parenthesized list, whereas variables declared in 
consecutive declarations are not necessarily stored contiguously. 

This causes each of the three identifiers, WIDTH, LENGTH, and HEIGHT, to be 
associated with 100 array elements of type REAL, so that 300 elements of type 
REAL have been declared in all. For each of these scalars, four contiguous bytes of 
storage are allocated. 
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4.1.1 Subscripted Variables 



To refer to a single element of a previously declared array, use the array name fol- 
lowed by a subscript enclosed in parentheses. This construct is called a subscripted 
variable. 

For example, as a result of the following DECLARE statement: 
DECLARE ITEMS (!□□) BYTE i 

each byte can be referenced as an individual item using ITEMS(O), ITEMS(l), 
ITEMS(2), and so on up to ITEMS(99). 

Notice that the first element of an array has subscript 0, not 1 . Thus, the subscript of 
the last element is 1 less than the dimension specifier. 

To add the third element of the array ITEMS to the fourth, and store the result in the 
fifth, write the PL/M assignment statement as follows: 

ITEMS(H) = ITEMS (S) + ITEMS(3)i 

The subscript of a subscripted variable need not be a whole-number constant. It 
can be another variable, or any PL/M expression that yields a BYTE, WORD, or 
INTEGER value for PL/M-86 and PL/M-286, or a BYTE, HWORD, WORD, 
OFFSET, SHORTINT, CHARINT, or INTEGER value for PL/M-386. 

Thus, the construction: 

VECTOR(ITEMSO) + 2) 

refers to some element of the array VECTOR. Which element this construction refers 
to depends on the expression ITEMS(3) + 2. This value, in turn, depends on the 
value stored in ITEMS(3), the fourth element of array ITEMS, at the time when the 
reference is processed by the running program. If ITEMS(3) contains the value 5, 
then ITEMS(3) + 2 is equal to 7 and the reference is to VECTOR(7), the eighth 
element of the array VECTOR. 

The following sequence of statements will sum the elements of the 10-element array 
NUMBERS by using an index variable named I, which takes values from to 9: 

DECLARE SUM BYTE^ /* To avoid overflown */ 

DECLARE NUMBERS (ID) BYTE i /* SUM should add up */ 

DECLARE I BYTE i /* to less than 255 */ 

SUM = 0=, 
DO I = □ TO 

SUM = SUM + NUMBERS ( I ) i 

END=, 
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Subscripted array variables can be used anywhere a variable can be used, including 
the left side of an assignment statement if the array elements are of a scalar type. 

4.2 Structures 

Just as an array enables one identifier to refer to a collection of elements of the same 
type, a structure enables one identifier to refer to a collection of structure members 
that may have different data types. Each member of a structure has a member 
identifier. 

A structure member can be another structure; these nested structures are described in 
Section 4.2.4. 

The following is an example of a structure declaration: 

DECLARE AIRPLANE STRUCTURE ( 
SPEED REAL-, 
ALTITUDE REAL); 

This statement declares two REAL scalars, both associated with the identifier 
AIRPLANE. Once this declaration has been made, the first scalar can be referred to 
as AIRPLANE. SPEED and the second as AIRPLANE . ALTITUDE . These names 
are also called the members of this structure. 

A structure can have many members (see Appendix B for the correct limit). The 
members of a structure are stored contiguously in the order in which they are speci- 
fied. (No storage is allocated for a based structure, but the members are considered to 
be contiguous in memory.) 

Individual structure members cannot be based and cannot have any attributes (see 
Chapter 3). 

4.2.1 Arrays of Structures 

With PL/M, arrays of structures can be created. The following DECLARE statement 
creates an array of structures that can be used to store SPEED and ALTITUDE for 20 
AIRPLANES instead of one: 

DECLARE AIRPLANE (5D) STRUCTURE ( 
SPEED REALn 
ALTITUDE REAL) 5 
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This statement declares 20 structures associated with the array identifier 
AIRPLANE, each distinguished by subscripts from to 19. Each of these struc- 
tures consists of two REAL scalar members. Thus, storage is allocated for 40 
REAL scalars. 

To refer to the ALTITUDE of the 17th AIRPLANE, write AIRPLANE(16). 
ALTITUDE. 

4.2.2 Arrays within Structures 

An array can be used as a member of a structure, as follows: 

declare paycheck structure ( 
last$name(15)byte-, 
first$nahe(is)bytEt 
hi byte-, 
amount real); 

This structure consists of two 15-element BYTE arrays, PAYCHECK. LAST$NAME 
and PAYCHECK. FIRST$NAME, the BYTE scalar PAYCHECK. MI, and the REAL 
scalar PAYCHECK. AMOUNT. 

To refer to the fourth element of the array PAYCHECK. LAST$NAME, write 
PAYCHECK. LAST$NAME(3). 

4.2.3 Arrays of Structures with Arrays inside the Structures 

Given that an array can be made up of structures, and a structure can have arrays as 
members, the two constructions can be combined to write: 

DECLARE FLOOR (3D) STRUCTURE ( 
OFFICE (SS) BYTE); 

The identifier FLOOR refers to an array of 30 structures, each of which contains one 
array of 55 BYTE scalars. This could be thought of as a 30-by-55 matrix of BYTE 
scalars. To reference a particular scalar value (for example, element 46 of structure 
25) write FLOOR(24).OFFICE(45). Note that the scalar elements of each OFFICE 
array are stored contiguously, and the OFFICE arrays are elements of the FLOOR 
array and are stored contiguously. 
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Alter the preceding PAYCHECK structure declaration to make it an array of struc- 
tures, as follows: 

DECLARE PAYROLL (!□□) STRUCTURE ( 
LAST$NAME(15)BYTE-, 
FIRST$NAME(15) BYTE-, 
MI BYTE i 
AMOUNT REAL); 



This is an array of 100 structures, each of which can be used during program execu- 
tion to store the last name, first name, middle initial, and amount of pay for one 
employee. LAST$NAME and FIRST$NAME in each structure are 15-byte arrays 
for storing the names as character strings. To refer to the Kth character of the first 
name of the Nth employee, write: 

PAYROLL (N-l) -FIRST$NAME(K-1) 

where N and K are previously declared variables to which appropriate values have 
been assigned. This might be convenient in a routine for printing out payroll 
information. 



4.2.4 Nested Structures 

A member of a structure can also be another structure; this is called a nested 
structure. 



Nested structures are subject to the same rules as all structures. They can contain 
their own member identifiers, whether these are scalars, arrays, or structures. 

The following example shows nested structures: 

DECLARE EMPLOYEE (100) STRUCTURE ( 
ID U0RD-, 

NAME STRUCTURE ( 

LASTSNAME (IS) BYTE-, 
FIRSTSNAME (IS) BYTE-, 
MI BYTE ) -, 
AGE BYTE-, 
JOB WORD-, 
PAY STRUCTURE ( 
RATE REAL-, 
OTRATE REAL-, 
BENEFITS STRUCTURE ( 
OPTIONS RE AL -i 
CHOSEN BYTE) 
) 

) \ 
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The preceding declaration statement is for an array (named EMPLOYEE) of 100 
structures. Each of the 100 elements of EMPLOYEE is a structure with the following 
members: a WORD scalar named ID, a nested structure called NAME, a BYTE 
scalar named AGE, a WORD scalar (HWORD for PL/M-386) named JOB, and a 
nested structure named PAY. 

The NAME structure has two arrays (LAST$NAME and FIRST$NAME) of 15 bytes 
each for members, as well as a BYTE scalar named MI. 

The PAY structure has two REAL scalars (RATE and OTRATE) for members, as well 
as a nested structure named BENEFITS. BENEFITS has the REAL scalar OPTIONS 
and the BYTE scalar CHOSEN as members. 

The preceding example contains two levels of nested structures. The structures 
NAME and PAY are at the first level of nesting; the structure BENEFITS is at the 
second level of nesting. See Appendix B for the maximum limit on nested structures. 

4.3 References to Arrays and Structures 

A variable reference is the use, in program text, of the identifier of a variable that has 
been declared. A variable reference can be fully qualified, partially qualified, or 
unqualified. 

4.3.1 Fully Qualified Variable References 

A fully qualified variable reference specifies a single scalar. For example, given the 
following declarations: 

DECLARE AVERAGE REALi 
DECLARE ITEMS (!□□) BYTE i 



DECLARE RECORD STRUCTURE ( 

KEY BYTE-, 

INFO WORD) i 
DECLARE NODE (25) STRUCTURE ( 

SUBLIST ( 1DD ) BYTE-, 

RANK BYTE) i 

then AVERAGE, ITEMS(5), RECORD. INFO, and NODE(21).SUBLIST(32) are all 
fully qualified variable references. Each refers unambiguously to a single scalar. 

Note that qualification can only be applied to variables that have been appropriately 
declared. A subscript can only be applied to an identifier that has been declared with 
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a dimension specifier. A member-identifier can be applied only to an identifier de- 
clared as a structure identifier. The compiler flags violations of these rules as errors. 

4.3.2 Unqualified and Partially Qualified Variable References 

Unqualified and partially qualified variable references can be used only in location 
references (described in Chapter 3) and in the built-in procedures LENGTH, LAST, 
and SIZE (described in Chapter 9). 

An unqualified variable reference is the identifier of a structure or an array, without a 
member- identifier or subscript. For example, with the declarations in the previous 
section, ITEMS and RECORD are unqualified variable references. An unqualified 
variable reference is a reference to the entire array or structure. ©ITEMS is the 
location of the entire array ITEMS (the location of its first byte). Similarly, 
©RECORD is the location of the first byte of the structure RECORD. 

A partially qualified variable reference does not refer to a single scalar even using a 
subscript and/or member-identifier with an identifier. 

For example, in the declaration in the previous section, NODE(15) and 
NODE(12).SUBLIST are partially qualified variable references. 

When used with the ©operator, partially qualified variable references are taken 
to mean the first byte that fits the description. Thus, @NODE(15) is the location 
of the first byte of the structure NODE(15), which is an element of the array 
NODE. Similarly, @NODE(12).SUBLIST is the location of the first byte of the 
array NODE(12).SUBLIST, which is a member of the structure NODE(12), 
which is an element of the array NODE. 

Because it is ambiguous, ©NODE.SUBLIST cannot be used. In a location refer- 
ence referring to an array consisting of structures, a subscript must be given 
before a member-identifier can be added to the reference. The rule is different for 
partially qualified variable references in connection with the built-in procedures 
LENGTH, LAST, and SIZE, as explained in Chapter 9. 
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A PL/M expression consists of scalar operands (values) combined by arithmetic, 
logical, and relational operators. For example: 

A + B 

A + B - C 

A*B + C/D 

A*(B + C) - (D - E)/F 

where + , — , *, and / are arithmetic operators for addition, subtraction, multiplica- 
tion, and division, and A, B, C, D, E, and F represent operands. The parentheses 
group operands and operators to control the order of evaluation. 

This chapter describes the rules governing PL/M expressions. Although these rules 
may appear complex, most of the expressions used in actual programs are simple. In 
particular, when the operands of arithmetic and relational operators are all of the 
same type, the resulting expression is easy to understand. 



Operands are the building blocks of expressions. An operand is a quantity with a 
value at run time on which an arithmetic, logical, or relational operation is performed 
by an operator. In the preceding examples, A, B, C, etc., are identifiers of scalar 
variables that have values at run time. 

Operands in expressions can also be numeric constants and fully qualified variable 
references. The following sections describe all of the types of operands that are 
permitted. 



A numeric constant can be an operand in an expression. However, its type must be 
appropriate, as discussed in the following paragraphs. 

A numeric constant that contains a decimal point is of type REAL. A numeric con- 
stant that does not contain a decimal point is a whole-number constant. 



5.1 Operands 



5.2 Constants 
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You can use a whole-number constant in either signed context or unsigned context. In 
unsigned context, a whole-number constant is treated as an unsigned binary number 
data type. In signed context, a whole-number constant is treated as a signed integer 
datatype. (See Table 3-2.) 

5.2.1 Whole-Number Constants in Unsigned Context 
PL/M-86/286 — 

I In PL/M-86 and PL/M-286, a whole-number constant in unsigned context is treated 
as follows: 

• As a BYTE value if it ranges from to 255 

• As a WORD value if it ranges from 256 to 65,535 

• As a DWORD value if it ranges from 65,536 to 4,294,967,295 (i.e., 2**32 - 1) 

I In PL/M-86 only, a single whole-number constant can also be treated as a POINTER 
or SELECTOR value. 

end 

PL/M-86/286 — 
PL/M-386 — 

In PL/M-386, a whole number constant in unsigned context is treated as follows: 
' • As a BYTE value if it ranges from to 255 

• As a HWORD value if it ranges from 256 to 65,535 

I* As a WORD value if it ranges from 65,536 to 4,294,967,295 (i.e. , 2**32 - 1) 
• As a DWORD value if it ranges from 2**32 to 2**64 - 1 

end 

PL/M-386 

5.2.2 Whole-Number Constants in Signed Context 

In signed context, a whole-number constant is always treated as an INTEGER value. 
In PL/M-86 and PL/M-286, the range is -32,768 to 32,767. 

In PL/M-386, the range is -2,147,483,648 to 2,147,483,647. Additionally, small 
integer values are extended into 32-bit values with no change to the arithmetic value. 
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5.2.3 String Constants 



A string constant containing not more than four characters can also be used as an 
operand. If a string constant has only one character, it is treated as a BYTE constant 
whose value is the 8-bit ASCII code for the character. If a string constant is a two- 
character string, it is treated as a WORD constant in PL/M-86 and PL/M-286, and as 
an HWORD constant in PL/M-386. The value of the two-character string is formed 
by stringing together the ASCII codes for the two characters, with the code for the 
first character forming the most significant 8 bits of the 16-bit number. 



PL/M-86/286 

I 



In PL/M-86 and PL/M-286, if a string constant is a three- or four-character string, it 

is treated as a DWORD constant whose value is formed by stringing together the 

ASCII codes for all of the characters. In a three-character string, the most significant 

16 bits of the 32-bit number are formed of 8 high-order zeros, then the code for the 

first character. In a four-character string, the code for the first two characters forms 

the most significant 16 bits of the number. 

end 

— PL/M-86/286 



I 




In PL/M-386, if a string constant is a three- or four-character string, it is treated as a 
WORD constant whose value is formed by stringing together the ASCII codes for all 
of the characters. The first character represents the high 8 bits, the second character 
represents the second most significant 8 bits, etc. If the string has three characters, 
the ASCII NUL character is inserted in front of the first character to form a four- 
character string. 

end 

— PL/M-386 



Strings of more than four characters are illegal as operands in expressions, and can 
be used in only two contexts: as initialization values for an array or as part of a 
location reference that points to the location at which the string constant is stored (see 
Chapter 3). 
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5.3 Variable and Location References 



As described in Chapter 4, fully qualified variable references uniquely specify a 
single scalar value. (Partially qualified references, also discussed in Chapter 4, have 
very restricted uses.) Any fully qualified variable reference can be used as an operand 
in an expression. When the expression is evaluated, the reference is replaced by the 
value of the scalar. 

A function reference is the name of a typed procedure that has been declared previ- 
ously, along with any parameters required by the procedure declaration. The value of 
a function reference is the value returned by the procedure. 

For example, in the statement: 
I = J + ABS ( L) i 

the absolute value of L will be returned by the function ABS and then added to the 
value of J before being stored in I. If L is —27, the result will be the same as writing: 
I = J + S7i 

For a complete discussion of procedures and function references, see Chapter 8. 
Location references are described in Chapter 3. 



5.4 Subexpressions 

A subexpression is an expression enclosed in parentheses, which can be used as an 
operand in an expression. A subexpression can be used to group portions of an 
expression together, just as in ordinary algebraic notation. 



5.5 Compound Operands 

All the operand types previously described are primary operands. An operand can 
also be a value calculated by evaluating some portion of the total expression. For 
example, in the expression: 
A + B*C 

(where A, B, and C are variable references), the operands of the * operator are B and 
C. The operands of the + operator are A, and the result of the compound operand 
B * C. Notice that this expression is evaluated as if it had been written as follows: 
A + ( B * C) 
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This analysis of an expression to determine which operands belong to which opera- 
tors, and which groups of operators and operands form compound operands, is dis- 
cussed in Section 5.9. Table 5-1 lists operator precedence. 

5.6 Arithmetic Operators 

PL/M has the following five principal arithmetic operators: 
+ - * / NOD 

These operators are used as in ordinary algebra to combine two operands. Each 
operand can have an unsigned binary number data type value; a signed integer data 
type value; or a REAL number data type value (except that REAL operands cannot be 
used with the MOD operator). 

Arithmetic operations cannot be used with POINTER and SELECTOR variables. 



Table 5-1 Operator Precedence 



Operator 
Class 


Operator 


Interpretation 


Precedence 





Controls order of evaluation: expressions 
within parentheses are evaluated before the 
action of any outside operator on the paren- 
thesized items 


Unary 


+ ■- 


Single positive operator, single negative 
operator 


Arithmetic 


V.MOD 

+ ,- 


Multiplication, division, modulo (remainder) 
division, addition, subtraction 


Relational 


<,<=,<>, 
= ,>=,> 


Less than, less than or equal to, not equal to, 
equals, greater than or equal to, greater than 


Logical 


NOT 
AND 
OR.XOR 


Logical negation 
Logical conjunction 
Logical inclusion disjunction, 
Logical exclusive disjunction 
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5.6.1 The + , -, *, and / Operators 



The operators +, — , *, and / perform addition, subtraction, multiplication, and 
division on operands of any data type except the POINTER and SELECTOR data 
types. The following rules govern these operations. 

1 . Both operands must be of the same class (i.e. , both operands must be unsigned, 
signed, or real). Mixing operands of different classes is illegal. However, an 
operand of one class can be converted, in an expression, to another class with the 
use of a built-in conversion function (see Chapter 9). 

2. Unsigned Arithmetic: 
Unsigned Addition and Subtraction 

If both operands are of the same data type, the result is of the same data type 
(e.g., BYTE + or - BYTE produces a BYTE result). 

If the operands are of different data types, the smaller operand is extended with 
high-order bits to the size of the larger operand; the addition or subtraction is 
then performed as though both operands are of the same type. For example, for 
BYTE + or - WORD, the BYTE operand is zero-extended by 8 bits to WORD 
size; then the operation is performed with the WORD operands to produce a 
WORD result. For a BYTE + or - DWORD the BYTE operand is zero- 
extended by 24 bits to DWORD size; then the operation is performed with the 
DWORD operands to produce a DWORD result. For WORD + or - DWORD, 
the WORD operand is zero-extended by 16 bits to DWORD size; then the opera- 
tion is performed with two DWORD operands producing a DWORD result. 

Unsigned Multiplication and Division 

PL/M-86/286 — 

I If both operands are of the same type, the result is of the same type as the 
operands with one exception: if both operands are of type BYTE, the * and / 
operations produce results of type WORD. 

end 

PL/M-86/286 — 
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— PL/M-386 

Assuming WORD32, if both operands are of type BYTE, the * and / operations 
produce an HWORD result; if both operands are of type HWORD, the * and / 
operations produce a WORD result. If both operands are of type WORD, the * 
and / operations produce a WORD result. If both operands are of type OFFSET, 
the * and / operations produce an OFFSET result. If both operands are of type 
DWORD, the * and / operations produce a DWORD result. 

For mixed unsigned operands, the same rules as for addition and subtraction 
apply. The smaller operand is zero-extended to the size of the larger operand, 
then the multiplication or division is performed as though both operands are of 
the same type. The results are as described in the preceding paragraph. 

If one operand is a whole-number constant or a string constant, it is treated as a 
HWORD or WORD depending on its value (see Sections 5.2.1 and 5.2.3). 

end 

— PL/M-386 



— PL/M-86/286 

3. Signed Arithmetic I 

All arithmetic for signed operands is signed integer arithmetic. If the whole- 
number constant exceeds 32,767, the operation is invalid. 

During signed arithmetic an expression can overflow only if it overflows the 
machine word. Assignment overflow is detected using the OVERFLOW control 
(see Chapter 11). 

Constants are always represented as integer constants, regardless of their value. 

end 

— PL/M-86/286 
— PL/M-386 

All arithmetic for signed operands is 32-bit signed integer arithmetic. The names 
of the storage type (e.g., CHARINT) do not imply what type of arithmetic is 
performed, only the size of storage assigned for the variable. 
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PL/M-386 

(continued) 



end 

PL/M-386 



During signed arithmetic an expression can overflow only if it overflows the 
machine word (32 bits). However, overflow is possible when the value is as- 
signed to a variable with SHORTINT or CHARINT data type. If the value is 
assigned to CHARINT, 24 high-order bits are truncated to form the CHARINT 
value. If the value is assigned to SHORTINT, 16 high-order bits are truncated to 
form the SHORTINT value. If the value is assigned to INTEGER, it is not 
changed. 

Assignment overflow is detected using the OVERFLOW control (see Chapter 11). 
Constants are always represented as integer constants, regardless of their value. 



4. Real Arithmetic 

Both operands are always of type REAL. Thus, the + , — , *, and / operations 
produce a result of type REAL. 

If one operand is a constant, it must be typed as a floating-point constant, that is, 
it must have a decimal point. Mixing REAL operands with whole-number con- 
stants is not allowed. For example, if R is a REAL variable, R+ 1.0 is a legal 
expression, but R + 1 is illegal. Also, 1 .0 + 1 is illegal, because it mixes a REAL 
constant with a whole-number constant. 

5. Arithmetic expressions containing operands of type SELECTOR or POINTER 
are illegal. 

6. If both operands are whole-number constants, the operation depends on the con- 
text in which it occurs, as explained in Section 5. 10. 1 . 

7. The result of division by is undefined, except for REAL values (see Appen- 
dix G). 

A unary — operator is also defined in PL/M. It takes a single operand, to which it is 
prefixed. A minus sign that has no operand to the left of it is taken to be a unary 
minus. 



A unary - operator makes ( — A) equivalent to (0 — A) , where A is any operand . The 
is a BYTE value if A is an unsigned binary number data type. The is an 
INTEGER value if A is a signed integer data type; or a REAL value if A is a real 
number data type. If A is a whole-number constant, its type and the unary — opera- 
tion depend on the context as explained in Section 5. 10. 1 . In unsigned context, ( — 1) 
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is assigned a BYTE value (0-1) which is equivalent to OFFH. In signed context, 
(-1) is assigned an INTEGER value (0-1) which is equivalent to OFFFFH for 
PL/M-86 and PL/M-286 and OFFFFFFFFH for PL/M-386. 

Finally, a unary + has no effect; ( + A) is equivalent to (A). 

5.6.2 The MOD Operator 

MOD performs division, except the result is not the quotient, but rather the remain- 
der left after integer division. The result has the same sign as the operand on the left 
side of the MOD operator. 

REAL operands cannot be used with the MOD operator; only unsigned or signed 
operands can be used. 

For example, if A and B are INTEGER variables with values of 35 and 16, respec- 
tively, then A MOD B yields an INTEGER result of 3, and - A MOD B yields - 3. 

Unlike the / operator, the MOD operator must be separated from surrounding letters 
and digits by blanks or other separators. 

5.7 Relational Operators 

The following relational operators are used to compare operands of the same type: 

< less than 

> greater than 

< = less than or equal to 

> = greater than or equal to 

< > not equal to 
= equal to 

Relational operators are always binary operators, taking two operands, to yield a 
BYTE result. Relational operators can be used with all types. 

If both operands are unsigned, then unsigned arithmetic will be used to compare the 
two values. As with the arithmetic operators, mixing unsigned data types is allowed, 
with the smaller operand being zero-extended to the size of the larger operand. 

Whole-number and string constant operands are treated as BYTE, WORD, or 
DWORD for PL/M-86 and PL/M-286, and as BYTE, HWORD, WORD, or OFF- 
SET for PL/M-386 (see Section 5.2.1). Unsigned data types are primarily used to 
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represent positive values. Negative numbers are represented by two's complement 
in the smallest unsigned data type that can hold the value. For example, —2 is 
represented as the BYTE value of OFEH. If B is a BYTE variable, then the rela- 
tional expression B > = - 2 is TRUE only if B has the value of 254 or 255, because 
the expression -2 (when evaluated unsigned) has a BYTE value of 254. 

In PL/M-86 and PL/M-286, if both operands are signed, then signed 16-bit integer 
arithmetic is used to compare the two values. In PL/M-386, if both operands are 
signed, then signed 32-bit integer arithmetic is used to compare the two values. 
CHARINT or SHORTINT are sign extended to INTEGER values. The calculated 
value is then assigned to the specified data type. 

If both operands are real, floating point arithmetic will be used to compare the two 
values. Only floating-point constants (i.e., constants containing a decimal point) can 
be mixed with REAL operands. 

Two POINTER operands can be compared for equality but greater than, less than, 
and inequality operations cannot be used. In PL/M-386, only two POINTERS are 
equal only if they are bitwise equal (i.e., if both segment selector portions are equal 
and both offset portions are equal). 

Two SELECTOR operands can be compared for equality, inequality, less than, and 
greater than. 

Since constants cannot be typed as POINTER or SELECTOR, comparison between 
POINTER or SELECTOR and constants is illegal. 

As with arithmetic operations, operands of different classes cannot be mixed together 
in relational operations. An operand of one class can be converted, in an expression, 
to another class using a built-in conversion function (see Chapter 9). 

If the specified relation between the operands is true, a BYTE value of OFFH (or 
llllSllllB) is returned. Otherwise, the result is a BYTE value of 00H (or 
0000S0000B). Thus, in all cases, the result is of type BYTE, with all 8 bits set to 1 
for a true condition, or to for a false condition. For example: 

(t>S) result is OFFH ("true") 
(b< = M) result is 00H ("false") 

Values of true and false resulting from relational operations are useful in conjunction 
with DO WHILE statements and IF statements, as described in Chapter 6. In the 
context of a DO WHILE statement or IF statement, only the least significant bit of a 
TRUE or FALSE value is used. Thus, each value with the least significant bit set 
(including OFFH) is considered TRUE and each value with the least significant bit 
is considered FALSE. A BYTE value is returned. 
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PL/M has the following four logical (Boolean) operators: 
NOT AND OR XOR 

These operators are used with the unsigned binary number data type, or whole- 
number or string constant operands to perform logical operations on 8, 16, or 32 bits. 

NOT is a unary operator, taking one operand only. It produces a result of the same 
type as its operand: each bit of the result is the one's complement of the correspond- 
ing bit of the original value. 

The remaining operators (AND, OR, XOR) each take two operands, and perform 
bitwise and, or, and exclusive or, respectively. The bits of an AND result are 1 only 
when the corresponding bit in each operand is 1 . The bits of an OR result are 1 when 
the corresponding bit of either operand is 1, and only when both operands are 0. 
The bits of an XOR result are only when the corresponding bits of the operand are 
the same (i.e., both 1 or both 0); the result has a 1 when one operand is 1 and the 
corresponding bit of the other operand is 0. 

When both operands are of the same type, the result is the same type as the operands. 

As with the arithmetic and relational operators, unsigned data types can be mixed in 
any combination for logical operations. Whole-number operands are treated as 
BYTE, WORD, or DWORD values in PL/M-86 and PL/M-286, and as BYTE, 
HWORD, or WORD values in PL/M-386 (see Section 5.2. 1). The only exception is 
an expression composed only of whole numbers within the cast parentheses; then the 
constants have integer context and the numbers are extended to the 16-bit signed 
value. The usual bitwise logical operation then takes place (as explained above for 
16-bit numbers for bitwise operations). In PL/M-386 only, mixing OFFSET with 
WORD produces an OFFSET result. 

The following are examples of logical operations: 

NOT 11 DDI ID OB result is 001 1001 IB 

10101010B AND 11001100B result is 10001 000B 

1D101D1DB OR 110D11DDB result is 1 1 101 1 10B 

1010 1010B XOR 11001100B result is 01 1001 10B 
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Note that true and false values resulting from relational operations can be combined 
with logical operators: 

N0T(b>S) result is 00H (false) 

(b>5) AND (1>2) result is 00H (false) 

(b>S) OR (1>5) result is OFFH (true) 

(LIU = Y)X0R(Z<2) result is OFFH (true) if LIM = Y and Z ^2 or if 

LIM< >Y and Z<2, but result is OOH (false) if 
both relations are true or both false 

Note that in the statement: 
A = (NOT B) 

parentheses must be used as indicated. Failure to do so will result in a syntax error 
because relational operators ( = ) have higher precedence than logical operators 
(NOT). 

The following are examples of whole numbers. In this example the parentheses en- 
close items to be converted (casted). 

OFFSET(10101010B AND 11001100B) gives OFFSET(OIOOOIOOOB). This is the 
result obtained with the simple logical operation written above, except that the offset 
type is returned (in addition, PL/M-386 will extend the answer to 32 bits). 

For PL/M-86 and PL/M-286, WORD(-4 AND 7) gives WORD(0FFFCH AND 
0007H) which gives WORD(4) or the unsigned 16-bit value of 4. 

For PL/M-386, HWORD (-4 AND 7) gives HWORD (OFFFFFFFCH AND 
00000007H) which gives HWORD(4) or the unsigned 16-bit value of 4. 



5.9 Expression Evaluation 

5.9.1 Precedence of Operators: Analyzing an Expression 

In PL/M, operators have an implied order that determines how operands and opera- 
tors are grouped and analyzed during compilation. 

The PL/M operators are listed in Table 5-1 from highest to lowest precedence; those 
that take effect first are listed first. Operators in the same line are of equal precedence 
and are evaluated as they are encountered in a left to right reading of an expression. 

The order of evaluation in an expression is controlled first by parentheses, then by 
operator precedence, and finally by left to right order. 
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The compiler first evaluates operands and operators enclosed in paired parentheses as 
subexpressions, working from the innermost to the outermost pairs of parentheses. 
The value of the subexpression is then used as an operand in the remainder of the 
expression. 

Parentheses are also used around both subscripts and the parameters of function or 
procedure references. These are not subexpressions, but they too must be evaluated 
before the remainder of the expressions or references can be evaluated at a higher 
level. 

When there is more than one operator in an expression, evaluate the results by begin- 
ning with the operator with the highest precedence. If the operators are of equal 
precedence, evaluate them left to right, as follows: 

Example Reason 

(A + B ) * C is not the same as A + B*C Parentheses form subexpressions 

A + B * C means the same as A + (B*C) Operator precedence 

A/B*C means the same as (A/B)*C Left to right, equal precedence 

The following are examples of precedence ranking: 

A + B * C is equivalent to A + ( B * C ) 

A + B - C * D is equivalent to (A + B) - (C * D ) 

A + B + C + D is equivalent to( (A + B) + C) + D 

A/B*C/D is equivalent to( (A/B) *C) / D 

A>B AND NOT B<C-1 is equivalent to ( A>B ) AND (N0T(B<(C-1) ) ) 

In the last four examples, the application of the left-to-right rule for operators with 
the same precedence is shown. In the second, third, and fifth examples, the left-to- 
right rule for operators of equal precedence makes no difference in the value of the 
expression. But in the fourth example, the left-to-right rule is critical. 

The following example shows the action of the rules of precedence on a longer 
expression: 

(-B + SflRT ( B*B - M.D * A * C ) )/(5-D * A) 



Assume A, B, and C are variables of type REAL, and SQRT is a procedure of type 
REAL which returns the square root of the value passed to it as a parameter. In this 
case, the parameter is the expression B*B — 4.0*A*C. Floating point constants (4.0, 
2.0) are used rather than whole-number constants (4,2) because it is invalid to com- 
bine whole-number constants with REAL variables. 
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The compiler first analyzes the portions of the expressions within the innermost 
parentheses, then the procedure parameter and the subexpression 2.0 * A. (The sub- 
expression is also called a compound operand because its result is used in evaluating 
the whole expression.) 

In a left-to-right scan, the two operands of the first * operator are both equal to the 
value of B. The operands of the second * operator are 4.0 and the value of A. The 
operands of the third * operator are the results of the second evaluation (i.e., the 
compound operand 4.0* A) and the value of C. The operands of the fourth * operator 
are 2.0 and the value of A. 

The subexpression 2.0* A is now completely analyzed, but the parameter expression 
still contains a minus ( — ) operator that has not been analyzed. The operands of this 
operator are the result of evaluating B*B and the result of evaluating 4.0*A*C. Once 
the evaluations are done, the parameter expression is analyzed and its value can be 
calculated. 

This value does not become an operand in the overall expression. It is passed to the 
procedure SQRT, which returns the square root of the parameter. This returned value 
then becomes an operand in the remainder of the full original expression: 
(-B + returned value) / (2-D * A) 

Now that the innermost subexpressions have been analyzed and evaluated, a division 
operator whose left operand must be evaluated further remains. This outer subexpres- 
sion is — B + the returned square root: there are two operators. The first is a 
unary minus ( — ) and its operand is the value of B. The second is the binary plus ( + ) 
operator, with two operands: the value of — B and the value of 
SQRT(B*B — 4.0*A*C). - B has the same meaning as - B, which is to be added to 
the known value of the square root indicated. The final operator is division (/). whose 
two operands are known: the value of ( — B + SQRT(B*B -4.0*A*C) ) and the value 
of (2.0* A). 

Three important points must be emphasized about expression evaluation, as dis- 
cussed in the next three sections. 

.2 Compound Operands Have Types 

Compound operands have types as do primary operands. All of the primary operands 
used in the preceding example were of type REAL, which results in compound oper- 
ands of type REAL. It is always valid for all the operands in an arithmetic expression 
to be of the same type, and the result will be that type also. Combining BYTE values 
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can validly create a WORD or HWORD value. Combining a signed integer data type 
value always creates an INTEGER value. 

In an expression containing mixed data types, any combinations can be used as long 
as the types belong to the same class (i.e., unsigned binary number, signed integer, 
real, pointer, or selector). Data types (of the same class) can be mixed as operands in 
expressions, whether they are constants or variables. 

Mixing types of different classes in arithmetic, logical, or relational expressions is 
invalid. For example, if F and G are INTEGER variables and H and K are REAL 
variables, then the expressions F > K and H + G are invalid. 

Due to operator precedence, some combinations can occur validly in the same ex- 
pression without being directly combined. In the following logical expression: 

(F > G AND H < K ) 

the subexpression F > G yields a BYTE value, as does the subexpression H < K. 
Then the BYTE values are ANDed together. This expression is legal despite an ap- 
parent mixing of types. G and H could not be the operands for two reasons: 

1 . The relational operators are of higher precedence than the AND operator. 

2. Only unsigned operands are legal with logical operators. 

5.9.3 Relational Operators Are Restricted 

In the absence of parentheses denoting a subexpression, the result of a relational 
operation (comparison) cannot become an operand in another relational operation. 
Thus, the expression: 

A <=X <=B 

is invalid in PL/M because the second < = operator would have to use the result of 
the first < = operator as one of its operands. 

In PL/M the valid expression is as follows: 
A <= X AND X <= B 

Parentheses also could have created a valid expression; for example: 
(A <= XX = B 
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However, in this expression the result does not have the desired meaning: A < = X 
becomes a byte of value if A is greater than X, OFFH if A is not greater than X. 
Thus, if A is 0, X is 1 , and B is 2: 

(0 < = 1) <= S 

evaluates to: 

(DFFHX = E 

and yields a FALSE value. This is contrary to the original intention. 

5.9.4 Order of Evaluation of Operands 

Operators and operands are not bound in the same order as the order in which oper- 
ands are evaluated. 

The rules of analysis specify which operands are bound to each operator. The follow- 
ing example is used to show how operands are bound to operators: 
A + B*C 

B and C are the operands of the * operator, and A and the value of B*C are the 
operands of the + operator. B and C must be evaluated before the * operation can be 
performed, and the compound operand B*C must be evaluated before the + opera- 
tion is performed. 

However, it is not obvious whether B will be evaluated before C or vice versa. A 
could be evaluated before either B or C, and its value stored until the + operation is 
performed. 

The rules of PL/M do not specify the order in which subexpressions or operands are 
evaluated in each statement. This flexibility enables the compiler to optimize the 
object code it produces, as described in Chapter 1 1 . In most cases, the order of 
evaluation makes no difference. However, certain embedded assignments (Section 
5. 1 1) or function references (Section 8.2) change the value of an operand in the same 
expression. 

5.10 Choice of Arithmetic: Summary of Rules 

As described in Chapter 3, PL/M uses three distinct kinds of arithmetic: unsigned, 
signed, and floating-point. Whenever an arithmetic or relational operation is carried 
out, PL/M uses one of these types of arithmetic, depending on the types of the 
operands. 
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Tables 5-2 and 5-3 are a summary of the rules that determine which type of arithmetic 
is used in each case. The tables also list the data type of the result for each kind of 
arithmetic operation. The notes following the table provide additional information. 
(See Sections 5.7 and 5.8 for rules governing relational and logical operations.) 

In PL/M-386, OFFSET operands are always 32-bit unsigned operands. 

In expressions, whole-number constants are always converted to the value of the 
equivalent data type. 



Table 5-2 Summary of Expression Rules for PL/M-86 and PL/M-286 



Variable 
Type 


Kind of 
Arithmetic 


Operand Type 


Arithmetic 
Operation 


Result 


Notes 


BYTE 

WORD 

DWORD 


Unsigned 


BYTE w/BYTE 


+ or - 

* or /or MOD 


BYTE 
WORD 


range: 0-255 
range: 0-65535 






DT 1 1 W/VVUnU 

becomes 
WORDw/WORD 


any 


VvUnU 


A BYTE operand is first extended 
with 8 high-order zeros to a WORD 
value. 






BYTEw/DWORD 
becomes 

DWORD w/DWORD 


any 


DWORD 


A BYTE operand is first extended 
with 24 high-order zeros to a 
DWORD value. 






WORDw/DWORD 
becomes 

DWORD w/DWORD 


any 


DWORD 


A WORD operand is first extended 
with 16 high-order zeros to a 
DWORD value. 


INTEGER 


Signed 


INTEGER 
w/INTEGER 


any 


INTEGER 


range: -32768 to +32767 


REAL 


Floating 
Point 


REALw/REAL 


+ or - or * 
or/ 


REAL 




POINTER 




POINTER 
w/POINTER 




BYTE 


OorOFFH 


SELECTOR 


Unsigned 


SELECTOR 
w/SELECTOR 


= , <>, <, 
or > 


BYTE 


OorOFFH 



Note: POINTER values are compared as full microprocessor addresses. SELECTOR values are 
compared as 16-bit unsigned numbers. 
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Table 5-3 Summary of Expression Rules for the PL/M-386 



Variable 
Type 


Kind of 
Arithmetic 


Dnprfinri Tunp 


OnAration 


Result 


Notes 


BYTE 
HWORD 


Unsigned 


BYTE w/BYTE 


+ or - 
*/or MOD 


BYTE 
HWORD 


range: to 255 
to 65,535 


WORD 
DWORD 




HWORD 
w/HWORD 


+ or - 
*/or MOD 


HWORD 
WORD 


range: 0-65,535 
0to2**32-1 






BYTE w/HWORD 
becomes HWORD 
w/HWORD 


+ or - 
*/orMOD 


HWORD 
WORD 


BYTE is extended 
with 8 high- 
order zeros to 
an HWORD value 






WORD w/WORD 


any 

arithmetic 


WORD 


range: 

0to2**32-1 






BYTE w/WORD 
becomes 
WORD w/WORD 


any 

arithmetic 


WORD 


BYTE is extended 
with 24 high- 
order zeros to a 
WORD value 






HWORD w/WORD 
becomes 
WORD w/WORD 


any 

arithmetic 


WORD 


HWORD is 
extended with 16 
high-order zeros 
to a WORD value 






DWORD w/DWORD 


any 

arithmetic 


DWORD 


range: 
0-2**63-1 






BYTE w/DWORD 
becomes DWORD 
w/DWORD 


any 

arithmetic 


DWORD 


BYTE is extended 
with 56 high- 
order zeros to a 
DWORD value 






HWORD w/DWORD 
becomes DWORD 
w/DWORD 


any 

arithmetic 


DWORD 


HWORD is 
extended with 48 
high-order zeros 
to a DWORD value 






WORD w/DWORD 
becomes DWORD 
w/DWORD 


any 

arithmetic 


DWORD 


WORD is 
extended with 32 
high-order zeros 
to a DWORD 
value 
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Table 5-3 Summary of Expression Rules for the PL/M-386 (continued) 



Variable 
Type 


Kind of 
Arithmetic 


Operand Type 


Operation 


Result 


Notes 


OFFSET 


Unsigned 


OFFSET 
w/OFFSET 


any 

arithmetic 


OFFSET 


range: 

0to2**32-1 






BYTE w/OFFSET 
becomes OFFSET 
w/OFFSET 


any 

arithmetic 


OFFSET 


BYTE is extended 
with 24 high- 
order zeros to an 
OFFSET value 






HWORD 
w/OFFSET 
becomes OFFSET 
w/OFFSET 


any 

arithmetic 


OFFSET 


HWORD is 
extended with 16 
high-order zeros to 
an OFFSET value 






WORD w/OFFSET 
becomes OFFSET 
w/OFFSET 


any 

arithmetic 


OFFSET 


range: 

0to2**32-1 






OFFSET 
w/DWORD 
becomes DWORD 
w/DWORD 


any 

arithmetic 


DWORD 


OFFSET is 
extended with 32 
high-order zeros to 
a DWORD value 


CHARINT 

SHORTINT 

INTEGER 


Signed 


INTEGER 
w/INTEGER 


+ or - 
*/or MOD 


INTEGER 


-2**31 to 
+ 2**31-1 


REAL 


Floating 
Point 


REAL w/REAL 


+ - *or/ 


REAL 




POINTER 




POINTER 
w/POINTER 




BYTE 


OorOFFH 


SELECTOR 


Unsigned 


SELECTOR 
w/SELECTOR 


= , <>, 
<, or > 


BYTE 


or OFFH 



Note: CHARINT and SHORTINT are sign extended to INTEGER before expression evaluation. 



The combinations of operands shown in Tables 5-2 and 5-3 are the only usable combi- 
nations of arithmetic operations and operands. For example, an operand of the signed 
integer data type cannot be combined with an operand of the unsigned binary number 
data type. However, explicit conversion can be coded in-line using the PL/M built-ins 
described in Chapter 9. 

5.10.1 Special Case: Constant Expressions 

The rules already given explain expressions like: 
A + 3 * B 
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where there is a single whole-number constant. However, if there is an expression 
like: 

3 - 5 + A 

then the kind of arithmetic that will be used to evaluate 3 — 5 must be considered, 
because both operands are whole-number constants. 

The answer, in this case, depends on the type of operand A. If A is an unsigned 
binary number, then 3 — 5 is considered to be in unsigned context. Unsigned arith- 
metic is used to evaluate 3-5, giving a BYTE result of 254. Unsigned arithmetic is 
then used to add this result to A. 

For PL/M-86 and PL/M-286, if A is a signed integer, then 3 — 5 is in signed context. 
Signed arithmetic is used to evaluate 3 — 5, giving an INTEGER result of —2. 
Signed arithmetic is then used to add this to A. 

For PL/M-386, if A is a signed integer, then 3 — 5 is in signed context. Signed 32-bit 
arithmetic is used to evaluate 3—5. Signed 32-bit arithmetic is then used to add this 
result to A. 

If A is of type REAL, POINTER, or SELECTOR, the expression is illegal. 

Any compound operand, subexpression, or expression that contains only whole- 
number constants as primary operands is called a constant expression. Floating-point 
constants are of type REAL and are treated as the values of REAL variables. 

In this expression: 

3 - S + 500 + A 

3 - 5 is a constant expression that forms part of the larger constant expression 3-5 
+ 500. 

If the constant expression is not the entire expression, its value is an operand in the 
expression. The context is created by the other operand of the same operator. 

In the preceding example, suppose the operand A has a BYTE value. Then the con- 
stant expression 3 — 5 + 500 is in unsigned context. The constants 3 and 5 are 
treated as BYTE values, and 500 is treated as a WORD or HWORD value. The 
operation 3—5 gives a BYTE result of 254, and this is extended to a WORD or 
HWORD value of 254 before adding 500. This results in a WORD or HWORD value 
of 754. It is exactly as if the expression had been written as follows: 
75^ + A 

For PL/M-86 and PL/M-286, if A had an INTEGER value, the constant 3 - 5 + 
500 would be in signed context; signed arithmetic is used for the operation 3 — 5, 
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which results in an INTEGER value of -2. Then 500 is added, and the INTEGER 
result is 498 which is added to the value of A. 

For PL/M-386, if A had a SHORTINT value, the constant 3+5-500 would be in 
signed context; signed 32-bit arithmetic is used for the operation 3 — 5 + 500. The 
result (498) is added to the value of A to form a 32-bit signed temporary result. 

In summary, if the context is created by an unsigned binary number data type oper- 
and, the constant expression is in unsigned context. If the context is created by a 
signed integer data type operand, the constant expression is in signed context. Note 
that if the context is created by a real number, pointer or selector data type operand, 
the constant expression is illegal. 

If the constant expression is the entire expression, then it is one of the following: 

• Constant expression as right-hand part of an assignment statement: context is 
created by the variable to which the expression is being assigned. Rules are given 
in Section 5.1 1. 

• Constant expression as subscript of an array variable: evaluated as if being 
assigned to an INTEGER variable (see Section 5.11). 

• Constant expression in the IF part of an IF statement: evaluated as if being 
assigned to a BYTE variable (see Sections 6.3 and 5.11). 

• Constant expression in a DO WHILE statement: evaluated as if being assigned to 
a BYTE variable (see Sections 6.1.3 and 5.11). 

• Constant expression as start, step, or limit expression in an iterative DO state- 
ment: evaluated as if being assigned to a variable of the same type as the index 
variable in the same iterative DO statement (see Sections 6. 1 and 5.11). 

• Constant expression in a DO CASE statement: evaluated as if being assigned to a 
WORD variable (see Sections 6. 1 and 5.11). 

• Constant expression as an actual parameter in a CALL statement or function 
reference: evaluated as if being assigned to the corresponding formal parameter 
in the procedure declaration (see Sections 8.2 and 5.11). 

• Constant expression in a RETURN statement: evaluated as if being assigned to a 
variable of the same type as the (typed) procedure that contains the RETURN 
statement (see Section 5.11). 

• Constant expression inside an explicit type conversion (cast built-ins); evaluated 
as if being assigned to an INTEGER variable, shorter values are extended to 16 
bits or 32 bits (see Section 5.11). The only exception is that relational operators 
can be used and are performed bitwise on 16-bit or 32-bit constant values. 
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5.11 Assignment Statements 



Results of computations can be stored as values of scalar variables. At any given 
moment, a scalar variable has only one value; however, this value can change with 
program execution. The PL/M assignment statement changes the value of a variable. 
Its simplest form is: 

variable = expression; 

where expression is any PL/M expression, as described in the preceding sections. 
This expression is evaluated, and the resulting value is assigned to (that is, stored in) 
the variable. This variable can be any fully qualified variable reference except a 
function reference. The old value of the variable is lost. 

For example, following execution of the statement: 
RESULT = A + Bi 

the variable RESULT will have a new value, calculated by evaluating the expression 
A + B. 



5.11.1 Implicit Type Conversions 

In an assignment statement, if the type of the value of the right-hand expression is not 
the same as the type of the variable on the left side of the equal sign, then either the 
assignment is illegal or an implicit type conversion occurs. For PL/M-86 and PL/M- 
286, all BYTE, WORD, or DWORD values are converted automatically. For PL/M- 
386, all unsigned binary number, signed integer and real data type values are 
converted automatically. Chapter 9 includes a description of built-in functions that, 
when invoked, perform explicit conversions for use in expressions or assignments. 

For implicit type conversions, the data type of the value on the right-hand side of the 
assignment statement is always coerced to equal the data type of the value on the left- 
hand side of the assignment statement. This is done either by extending the value of 
the expression, or by truncating the value of the expression by the appropriate num- 
ber of high-order bits so that the data types of both sides of the assignment statement 
are the same. 

The implicit type conversions that occur for assignment statements are summarized 
in Tables 5-4 and 5-5. 
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Table 5-4 Implicit Type Conversions in Assignment Statements for 
PL/M-86 and PL/M-286 



Expression 

Doc lilt Tt/na 

nesuu iype 


Variable on 
Left of 

Accinn m ont 
Mooiytlliitri 1 1 

Statement 


Conversion 


BYTE 


WORD 


RVTF wqImq ic ovtonHoH h\/ R hinh-nrH^r H hitc 

□ ML VctlUCT to CAtCl IUcU Uy O 1 My 1 l~UI UCI \J UlLo 

to WORD value 




RVTF \/ah ia ic DvtonrloH hw hinh-nrHor fl Kite 
□ TIC Value lo tJAlcflUtrU Uy cJ+ Iliyil-UlUcI V Ullo 

to DWORD value 


WORD 


RVTF 


ft hinh r\rriar hitc r^i lA/ORn \/qIiio aro tn mratorl 
O 1 liy 11 LM Ucl UlLo Ul VVUnL/ VctlUU alC LI UMLvCUCU 

to convert it to a BYTE value 


DWORD 


WORD value is extended bv 16 hiah-order 
bits to DWORD value 


DWORD 


BYTE 


24 high-order bits of DWORD value are trun- 
cated to convert it to a BYTE value 


WORD 


16 high-order bits of DWORD value are trun- 
cated to convert it to a WORD value 



Table 5-5 Implicit Type Conversions in Assignment Statements 
for PL/M-386* 



Expression 
Result Type 


Variable on 

Left of 
Assignment 
Statement 


Conversion 


BYTE 


HWORD 


BYTE value is extended by 8 high-order bits 
to HWORD value 


WORD 


BYTE value is extended by 24 high-order bits 
to WORD value 


DWORD 


BYTE value is extended by 56 high-order bits 
to DWORD value 


OFFSET 


BYTE value is extended by 24 high-order bits 
to OFFSET value 


HWORD 


BYTE 


8 high-order bits of HWORD value are trun- 
cated to convert it to a BYTE value 


WORD 


HWORD value is extended by 16 high-order 
bits to convert it to a WORD value 



•Assuming WORD32 
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Table 5-5 Implicit Type Conversions in Assignment Statements 
for PL/M-386 (continued)* 



Expression 
Result Type 


Variable on Left 
of Assignment 

Qtatorriont 


Conversion 


HWORD 
(continued) 


DWORD 


HWORD value is extended by 48 high- 
oraer u dus io convert it to a uwuhu value 


OFFSET 


HWORD value is extended by 16 high- 
oratjr u du& 10 convert u 10 an urrot i 
value 


WORD 


DVTP 
Dl 1 t 


^4 nign-oraer diis ot vvunu vaiue are Trun- 
cated to convert it to a BYTE value 


n \v\jr\u 


id nign-oraer Dits ot wunu vaiue are trun- 
cated to convert it to a HWORD value 


DVVUrtU 


WORD value is extended by 32 high-order 
bits to convert it to a DWORD value 


Urrot 1 


i\o conversion (Dotn wuhu ana urrot i 
are 32-bits) 


DWORD 


RVTP 

Dl It 


Kfl Vt t~t /-\ r r\ r Kite* r\i V~\\ D PI \ in 1 r ■ a -~> r r\ 

oo nign-oraer diis ot uwunu vaiue are 
truncated to convert it to BYTE value 


n VVUrtU 


AO kink AK/^Ar UjlA n f niA/PlDPl w aIi i a n vn 

4o nign-oraer Dits ot uwuhu value are 
truncated to convert it to HWORD value 


\A/nnn 
VvUrtU 


od nign-oraer uits ot uwumu vaiue are 
truncated to convert it to WORD value 


Urrot 1 


o o kink w f\ «-w »- U- i -i. ~ n x r~\\ a //— \ i j r~\ _ , i , , _ _ ^ _ 

o<i nign-oraer uits ot uwuhu value are 
truncated to convert it to OFFSET value 


OFFSET** 


Dl 1 t 


24 high-order bits of OFFSET value are 
truncated to convert it to a BYTE value 


nWUHU 


■AC kink nv^Jnv k*4-n £ (~ \ I - T~ Of" - T" 

lb nigh-order bits or OFFSET value are 
truncated to convert it to a HWORD value 


WUHL) 


No conversion is necessary (both WORD 
and OFFSET are 32 bits) 


UWUnU 


/"* 1 1 1 T lln |,,. I— n»»±« « *J .m. J La... OO kink 

Urrbh I value is extended by 32-high- 
order bits to convert it to a DWORD value 


INTEGER 


CHARINT 


24 high-order bits of INTEGER value are 
truncated to convert it to CHARINT value 


SHORTINT 


16 high-order bits of INTEGER value are 
truncated to convert it to SHORTINT value 


REAL 


REAL 


Automatically converted to 32-bit value 



'Assuming WORD32 
**A warning message is issued if OFFSET values are truncated. 
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— PL/M-86/286 

Expression with an INTEGER value: No implicit conversions are performed. If the 
variable on the left side of the assignment statement is a type other than INTEGER, 
the assignment is illegal. 

Expression with a REAL value: No implicit conversions are performed. If the vari- 
able on the left side of the assignment statement is a type other than REAL, the 
assignment is illegal. 

Expression with a POINTER value: No implicit conversions are performed. If the 
variable on the left side of the assignment statement is a type other than POINTER, 
the assignment is illegal. 

Expression with a SELECTOR value: No implicit conversions are performed. If the 
variable on the left side of the assignment statement is a type other than SELECTOR, 
the assignment is illegal. 

end 

— PL/M-86/286 



— PL/M-386 

Note that implicit conversion is not performed for POINTER or SELECTOR values. 
For assignment statements with POINTER or SELECTOR expressions, the left side 
of the assignment statement would be of the same type as the expression. 

— PL/M-386 



5. 11 .2 Constant Expression 

BYTE variable on the left: The constant expression is evaluated in unsigned context. 
If the resulting value is equal to or greater than and equal to or less than 255, it is 
treated as a BYTE value and no conversion is necessary. If the resulting value is 
greater than 255, it is truncated to type BYTE by dropping all except its 8 low-order 
bits. 

INTEGER variable on the left: The constant expression is evaluated in signed con- 
text. No conversion is necessary. 

REAL variable on the left: The assignment is illegal unless all values on the right are 
floating-point constants. If the value of the constant expression is out of the range for 
REAL variables, an overflow exception occurs (see Section 10.6 and Appendix G). 
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PL/M-86 — 

I POINTER variable on the left: If the constant expression consists only of a single 
whole-number constant, the constant is treated as a POINTER value. The whole- 
number constant must not be greater than 1,048,575. If the constant expression is a 
value other than a single whole-number constant, the assignment is illegal. This is 
one of the three cases in which a whole-number constant can be treated as a 
POINTER value. The other two cases are described in Sections 3.4.5 and 3.5. 

SELECTOR variable on the left: If the constant expression consists only of a single 
whole-number constant, it is treated as a SELECTOR value. The whole-number con- 
stant must not exceed 65,535. If the constant expression is a value other than a single 

I whole-number, the assignment is illegal. This is one of two cases where a whole- 
number constant can be treated as a SELECTOR value. The other case is described in 
section 3.4.7. 

end 

PL/M-86 — 
PL/M-86/286 — 

WORD variable on the left: The constant expression is evaluated in unsigned context. 
If the resulting value is equal to or greater than and equal to or less than 65,535, it is 
treated as a WORD value, and no conversion is necessary. If the resulting value is 
greater than 65,535, it is truncated to type WORD by dropping all except its 16 low- 
order bits. 

I DWORD variable on the left: The constant expression is evaluated in unsigned con- 
text. No conversion is necessary. 

end 

PL/M-86/286 — 
PL/M-286 — 

POINTER variable on the left: The assignment is illegal. 

SELECTOR variable on the left: The assignment is illegal, 
end 

PL/M-296 
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— PL/M-386 

HWORD variable on the left: The constant expression is evaluated in unsigned con- 
text. If the resulting value is equal to or greater than and equal to or less than 
65,535, it is treated as an HWORD value, and no conversion is necessary. If the 
resulting value is greater than 65,535, it is truncated to type HWORD by dropping all 
except its 16 low-order bits. 

WORD variable on the left: The constant expression is evaluated in unsigned context. 
No conversion is necessary. 

DWORD variable on the left: The constant expression is evaluated in unsigned con- 
text and is zero-extended to a DWORD value. 

OFFSET variable on the left: The constant expression is evaluated in unsigned con- 
text. No conversion is necessary. 

CHARINT variable on the left: The constant expression is evaluated in 32-bit 
INTEGER arithmetic. If the value is less than - 128 or greater than + 127, it is trun- 
cated to 8 bits. 

SHORTINT variable on the left: The constant expression is evaluated in 32-bit 
INTEGER arithmetic. If the value is outside the given range for SHORTINT 
( - 32,768 to + 32,767), it is truncated to 16 bits. _ 

Constants cannot be assigned to POINTER or SELECTOR variables. 

end 

PL/M-386 

Type conversion built-ins can be used to change the type of a constant expression to 
the type required for assignment. The entire expression within the type conversion is 
evaluated in signed context. 

5.11.3 Multiple Assignment 

It is often convenient to assign the same value to several variables at the same time. 
This is accomplished in PL/M by listing all the variables to the left of the equal sign, 
separated by commas. The variables LEFT, CENTER, and RIGHT can all be set to 
the value of the expression INIT + CORR with the single assignment statement: 
LEFT i CENTER -> RIGHT = INIT + CORR i 



Expressions and Assignments 



The variables on the left-hand side of a multiple assignment must be all of the same 
class, that is, all unsigned, all signed, all pointer, all selector, or all real. Then the 
conversion rules described previously in this chapter are applied separately to each 
assignment. 



NOTE 

The order in which the assignments are performed is not guaranteed. There- 
fore, if a variable on the left side of a multiple assignment also appears in the 
expression on the right side, the results are undefined. 



5. 11 .4 Embedded Assignments 

A special form of assignment can be used within PL/M expressions. The form of this 
embedded assignment is: 

variable: = expression 

and can appear anywhere an expression is allowed. The expression (everything to the 
right of the : = assignment symbol) is evaluated and stored in the variable on the left. 
Parentheses are used to specify the limits of an embedded assignment within an as- 
signment statement. The value of the embedded assignment is the same as that of its 
right half. For example, the expression: 

ALT + (CORR := TCORR + PCORR) - (ELEV := HT/SC ALE ) 

results in exactly the same value as: 

ALT + (TCORR + PCORR) - ( HT/SC ALE ) 

except that the intermediate results TCORR + PCORR and HT/SCALE are stored in 
CORR and ELEV, respectively. These names for intermediate results can then be 
used at a later point in the program without recalculating their values. The names 
must have been declared earlier. 



NOTE 

The rules of PL/M do not specify the order in which subexpressions or oper- 
ands are evaluated. When an embedded assignment changes the value of a 
variable that also appears elsewhere in the same expression, the results cannot 
be guaranteed. 

For example, the following expression: 

A = (X:=X + M) + Y* Y + X =, 

could mean either of the following interpretations: 

Al = (X + M) + Y*Y + (X + M) i 
AS = (X+M) + Y*Y + Xi 

Avoid this ambiguity by removing the embedded assignment from the expres- 
sion and using a separate assignment statement to achieve the desired effect as 



follows: 












1 X 




X 


+ 






Al 




X 


+ 


Y*Y 


+ Xn 


S X 




X 


+ 


H\ 




A5 




X 


+ 


Y*Y 


+ X - H--, 


3 A3 




X 


+ 


M + 


Y*Y + X=, 


X 




X 


+ 


■M 
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FLOW CONTROL STATEMENTS 



This chapter describes statements that alter the sequence of PL/M statement execu- 
tion and that group statements into blocks. 



6.1 DO and END Statements: DO Blocks 

Procedures and DO blocks are the basic building units of modular programming in 
PL/M. (Procedures are discussed in Chapter 8.) 

This chapter discusses all four kinds of DO-blocks. Each DO block begins with a DO 
statement and includes all subsequent statements through the closing END statement. 
The four kinds of DO blocks are as follows: 

• Simple DO block 

DOi /* all statements executed-, each in order */ 

statement-O'i 
statement-1 \ 
statement-3'i 

END i 

• DO CASE block 

DO CASE select— expressions /* exactly one statement executed */ 

case-0-stateaent\ /* executed if select_expression = */ 

case-l-statementi /* executed if select_expression = 1 */ 

/* etc- */ 

end; 

• DO WHILE block 

DO WHILE expression_true\ 

statement-0\ /* all executed repeatedly if expression is */ 

statement-!; /* true-, none executed if expression false- */ 

END; 
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• Iterative DO block 



DO counter = start-expr TO limit-expr BY step-expr'i 

statement-0\ /* all statements executed a number */ 

statement-l\ /* of times depending on comparison */ 

/* of counter with limit expr. */ 

END =i 

The last two blocks are also referred to as DO-loops because the executable state- 
ments within them can be executed repeatedly (in sequence) depending on the expres- 
sions in the DO statement. 

Any DO statement can have multiple labels on it, and only the last of these can appear 
between the word END and the next semicolon. For example: 

A: B: C: D: EM: DOi 



END EM '-,/* indicates end of block EN; */ 
/* An B-. Ci D also end here- */ 

As mentioned in Chapter 3, the placement of declarations is restricted. Except for use 
in procedures, declarations are permitted only at the top of a simple DO block, before 
any executable statements of the block. (This DO can, of course, be nested within 
other DOs or procedures. Chapter 7 discusses the scope of declared names.) 

Each DO block can contain any sequence of executable statements, including other 
DO blocks. Each block is considered by the compiler as a unit, as if it were a single 
executable statement. This fact is particularly useful in the DO CASE block and the 
IF statement, both discussed in this chapter. 

The discussions that follow describe the normal flow of control within each kind of 
DO block. The normal exit from the block passes through the END statement to the 
statement immediately following. These discussions assume that none of the state- 
ments in the block causes control to bypass that process. A GOTO statement with the 
target outside the block would be one such bypass. (GOTOs are discussed later in this 
chapter.) 
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6.1.1 Simple DO Blocks 



A simple DO block merely groups, as a unit, a set of statements that will be executed 
sequentially (except for the effect of GOTOs or CALLs): 

DO'-, 

statement-0\ 
statement-1 i 

statement-n i 
END i 

For example: 

DOn 

NEWSVALUE = OLDSVALUE + TEnP i 
COUNT = COUNT + li 
END i 

This simple DO block adds the value of TEMP to the value of OLD$VALUE and 
stores it in NEW$ VALUE. It then increments the value of COUNT by one. 

DO blocks can be nested within each other as shown in the following example: 
ABLE: DOn 

statement-O't 
statement-1 i 
BAKER: DOi 

statement-a'-, 

statement-b'-, 

statement-c i 
END BAKER i 
statement-? 1 ! 
statement-3\ 

END ABLE; 

The first DO statement and the second END statement bracket one simple DO block. 
The second DO statement and the first END statement bracket a different DO block 
inside the first one. Notice how indentation (using tabs or spaces) can be used to 
make the sequence more readable, so that it can be seen at a glance that one DO block 
is nested inside another. It is recommended that this practice be followed in writing 
PL/M programs. See Appendix B for the number of DO blocks that can be nested. 

A simple DO block can delimit the scope of variables, as discussed in Chapter 7. 
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6.1.2 DO CASE Blocks 



A DO CASE block begins with a DO CASE statement, and selectively executes one 
of the statements in the block. The statement is selected by the value of an expression. 
The maximum number of cases is given in Appendix B. The form of the DO CASE 
block is: 

DO CASE select— expression - -, 
statement-0\ 
statement-1 \ 

statement-n\ 

ENDi 

In the DO CASE statement, select_expression must yield an unsigned binary number 
(excluding DWORD) or a signed integer value. If the expression is a constant expres- 
sion, it is evaluated as if it were being assigned to a WORD variable. The value (call 
the value K) must be between and n, inclusive. K is used to select one of the 
statements in the DO CASE block, which is then executed. The first case (statement- 
0) corresponds to K = 0; the second (statement-1) corresponds to K = 1 , and so 
forth. Only one statement from the block is selected. This statement is then executed 
(only once). Control then passes to the statement following the END statement of the 
DO CASE block. 

NOTE 

If the run-time value of the expression in the DO CASE statement is less than 
or greater than n (where n + 1 is the number of statements in the DO CASE 
block), the effect of the DO CASE statement is undefined. This may have 
disastrous effects on program execution. Therefore, if there is any possibility 
that this out-of-range condition may occur, the DO CASE block should be 
contained within an IF statement that tests the expression to make sure that it 
has a value that will produce meaningful results. 

An example of a DO CASE block is: 
DO CASE SCORE i 

C0NVERSI0NS=C0NVERSI0NS + M 
SAFETIES = SAFETIES + 1% 
FIELDGOALS = FIELDGOALS + Jl 



1 

T0UCHD0UNS = T0UCHD0WNS + 1 =, 
ENDi 



/* case □ */ 

/* case 1 */ 

/* case S */ 

/* case 3 */ 

/* case */ 

/* case S */ 

/* case t */ 
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When execution of this CASE statement begins, the variable SCORE must be in the 
range to 6. If SCORE is 0, 4, or 5 then a null statement (consisting of only a 
semicolon, and having no effect) is executed; otherwise the appropriate statement is 
executed, causing the corresponding variable to be incremented. 



A more complex DO CASE block is the following: 
SELECT = COUNT - 5* 

IF SELECT <= 2 AND SELECT >= THEN 
DO CASE SELECTS 

X = X + 1; /* Case □ */ 

DO; /* Begin Case 1 */ 

X = Y + 10=i 
Y = Y + 1=, 

END ; /* End Case 1 */ 

DO I = LASTSHI + 1 TO TOP - M/* Begin Case 5 */ 
Z(I) = X * V + li 
U(I) = Z(I) * Z(I); 

v(i) = urn - za>; 

END; /* End Case 5 */ 

END; /* End DO CASE block */ 

ELSE CALL ERROR; 

If SELECT and COUNT are INTEGER variables, negative values could occur. The 
DO CASE block is placed within an IF statement to guarantee that execution of the 
DO CASE block will not be attempted if the value of SELECT is less than or 
greater than 2. Instead, a procedure called ERROR (declared previously) will be 
activated. IF statements are discussed in Section 6.3. 

The preceding example illustrates the use of a simple DO block as a single PL/M 
statement. The DO CASE statement can select Case 1 or Case 2 and cause multiple 
statements to be executed. This is only possible because they are grouped as a simple 
DO block, which acts as a single statement. 
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6.1.3 DO WHILE Blocks 



DO WHILE and IF statements examine only the least significant bit of the value of 
the expression. If the value is an odd number (least significant bit = 1), it will be 
considered true. If it is even (least significant bit = 0), it will be considered false. If 
the expression is relational, e.g., A <B, the result will have a value of 00H or OFFH, 
but this is incidental; it may have any unsigned value. 

A DO WHILE block begins with a DO WHILE statement, and has the following 
form: 

DO WHILE expression'-, /* expression must yield an unsigned value */ 
statement-0\ 
statement-1 \ 

statement-ni 

ENDi 

The effect of this statement is as follows: 

1 . First the unsigned expression following the reserved word WHILE is evaluated. 
If the rightmost bit of result is 1 , then the sequence of statements up to the END 
is executed. 

2. When the END is reached, the expression is evaluated again, and again the 
sequence of statements is executed only if the value of the expression has a 
rightmost bit of 1 . 

3. The block is executed over and over until the expression has a value whose 
rightmost bit is 0. Execution then skips the statements in the block and passes to 
the statements following the END statement. 

Consider the following example: 

AMOUNT = H 

DO WHILE AMOUNT <= 3i 

AMOUNT = AMOUNT + li 

END i 

The statement AMOUNT = AMOUNT + 1 is executed exactly 3 times. The value 
of AMOUNT when program control passes out of the block is 4. 
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6.1.4 Iterative DO Blocks 



An iterative DO block begins with an iteration statement and executes each statement 
in the block, in order, repeating the entire sequence. The form of the iterative DO 
block is: 

DO counter = start-expr TO limit-expr BY step-expr \ 
statement-0 \ 
statement-1 ; 



END ; 

The BY step-expr phrase is optional; if omitted, a step of 1 is the default. 

For PL/M- 86 and PL/M-286, the counter must be a non-subscripted variable of un- 
signed type: BYTE or WORD, or a signed integer data type: INTEGER. For PL/M- 
386, the counter must be a non-subscripted variable of unsigned type: BYTE, 
HWORD, WORD, or OFFSET, or a signed integer data type: INTEGER, 
CHARINT, or SHORTINT. 

An example of an iterative DO block is: 
DO I = 1 TO ID; 

call bell; 

end; 

where BELL is the name of a procedure that causes a bell to ring. The bell will ring 
ten times. 

Another example shows how the index-variable can be used within the block: 

AMOUNT = □; 

DO I = 1 TO id; 

AMOUNT = AMOUNT + I; 

end; 

The assignment statement is executed 10 times, each time with a new value for I. The 
result is to sum the numbers from 1 to 10 (inclusive) and leave the sum (namely, 55) 
as the value of AMOUNT. 

The next example uses step-expr. 

/* Compute the product of the first N odd integers */ 
PROD = l; 

DO I = 1 TO (S*N-1) BY 5; 
PROD = PR0D*I; 

END ; 
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The type of counter (signed or unsigned) affects the following factors in the execution 
flow of iterative DOs: 



• When step-expr is evaluated. 

• What causes execution to exit the DO block. 

The following steps constitute the general execution sequence of an iterative DO 
block, with both signed and unsigned variables and expressions in the DO itself. Type 
is mentioned only for steps in which actions or consequences vary according to type. 
Where the signed case is different, it is described in parentheses. The discussion 
following this description summarizes the rules and their results for signed and un- 
signed data types. 

1 . The start-expr is evaluated and assigned to counter. 

2. The limit-expr is evaluated and compared with counter. (If counter and limit-expr 
are of signed type, then step-expr is also newly evaluated at this time.) 

a. If counter is greater than limit-expr, execution exits the DO and passes to the 
statement following the next END (unless step-expr is a negative signed 
value; if so, the exit occurs only if counter is less than limit-expr). 



b. Otherwise, the statements within the DO block are executed in order until the 
END statement is reached. 

c. At the END, a step-expr of unsigned type (BYTE or WORD for PL/M-86 
and PL/M-286, and BYTE, HWORD, or WORD for PL/M-386) is newly 



3. The counter is incremented by the value of step-expr. For unsigned counters, if 
the new value is less than the old value (due to modulo arithmetic as explained 
next), the loop is exited immediately. Otherwise, control returns to step 2. 

An 8-bit BYTE can represent numbers no larger than 1 1 1 1 1 1 1 IB (255 decimal). The 
largest number a 16-bit WORD (or HWORD) can represent is 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 IB, 
which is 65535 decimal. The largest number a 32-bit WORD can represent is 
OFFFF$FFFFH, which is 4,294,967,295 decimal. Adding 1 to these values gives a 
result of 0. Thus, the new counter can be less than the old. 



evaluated. 
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These rules and their consequences can be summarized in two broad cases: 

1 . Starting with a non-negative step-expr, then the loop is exited as soon as any one 
of the following conditions become true: 

a. The new counter is greater than the new limit-expr. 

b. A signed step-expr becomes negative AND the new counter is still less than 
the new limit-expr. 

c. An unsigned step-expr causes a lower counter than the one just used. 

2. When starting with a negative and signed step-expr, then the loop is exited as 
soon as either of the following two conditions occurs: 

a. The new counter is less than the new limit-expr. 

b. The new step-expr becomes non-negative AND the new counter is greater 
than the new limit-expr. 

Upon exit from the iterative DO block: 

1 . In all cases step-expr has been reevaluated. 

2. In all but one case limit-expr has been reevaluated. When an unsigned counter 
has just gone over and become smaller, limit-expr is unchanged from its value 
during the last loop. 

3. In all cases counter has been changed, but the step value that was added to it 
varies. If signed, counter has been incremented by the former step value before it 
was reevaluated. For unsigned counters, the newer step has been used. 

The following distinctions are important: 

• In every case, start-expr is evaluated only once and limit-expr is evaluated before 
any execution. 

• A signed step-expr is evaluated in step 2; other step-exprs are evaluated in step 3. 

• With an unsigned counter, there cannot be a negative step. Furthermore, stepping 
down to a limit-expr that is less than start-expr is not possible because the loop 
will be exited immediately. 
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6.2 END Statement 



An END statement must terminate all DO blocks. An END statement has the follow- 
ing syntax: 

END [name]; 



name is the optional name that (if present) should match the label of the 
corresponding DO statement. 



The IF statement provides conditional execution of statements. It takes the form: 
IF expression THEN statement-aS 



The reserved word THEN and the statement following it are required and are called 
the THEN part. The reserved word ELSE and the statement following it are optional, 
and are called the ELSE part. 

The IF statement has the following effect: first expression is evaluated as if it were 
being assigned to a variable of type BYTE. If the result is true (rightmost bit is 1) 
then statement-a is executed. If the result is false (rightmost bit is 0), then statement-b 
is executed. Following execution of the chosen alternative, control passes to the next 
statement following the IF statement. Thus, of the two statements {statement-a and 
statement-b) only one is executed. 

Consider the following program fragment: 

IF NED > OLD THEN RESULT = NEbl i 
ELSE RESULT = OLD i 

Here, RESULT is assigned the value of NEW or the value of OLD, whichever is 
greater. This code causes exactly one of the two assignment statements to be exe- 
cuted. RESULT always gets assigned some value, but only one assignment to 
RESULT is executed. 

In the event that statement-b is not needed, the ELSE part may be omitted entirely. 
Such an IF statement takes the form: 

IF expression THEN statement-a; 



Where: 



6.3 IF Statement 



ELSE statement-b'i 



/*optional*/ 
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Here, statement-a is executed if the value of expression has a rightmost bit of 1. 
Otherwise, nothing happens, and control immediately passes on to the next statement 
following the IF statement. 

For example, the following sequence of PL/M statements will assign to INDEX 
either the number 5, or the value of THRESHOLD, whichever is larger. The value of 
INIT will change during execution of the IF statement only if THRESHOLD is 
greater than 5. The final value of INIT is copied to INDEX in any case: 
INIT = Sn 

IF THRESHOLD > INIT THEN INIT = THRESHOLDS 
INDEX = INIT; 

The power of the IF statement is enhanced by using DO blocks in the THEN and 
ELSE parts. Since a DO block can be used wherever a single statement can be used, 
each of the two statements in an IF statement may be a DO block. For example: 

if a = b then 
do; 

E(2UAL<?EVENTS = EflUALSE VENTS + 1; 
PAIR5VALUE = A; 
BOTTOM = B; 

END; 

ELSE 

do; 

UNE(3UAL$EVENTS = UNEflUALSEVENTS + 1; 
TOP = a; 
BOTTOM = B; 

end; 

DO blocks nested within an IF statement can contain further nested DO blocks, IF 
statements, variable and procedure declarations, and so on. 

6.3.1 Nested IF Statements 

Any IF statement (including the ELSE part, if any) can be considered a single PL/M 
statement (although it is not a block). Thus, the statement to be executed in a THEN 
or an ELSE clause may in fact be another IF statement. 

An IF statement inside a THEN clause is called a nested IF. Nesting may be carried to 
several levels without needing to enclose any of the nested IF statements in DO 
blocks, as in the following construction: 

IF expression-1 THEN 

IF expression-E THEN 

IF expression-3 THEN statement-a; 
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Here are three levels of nesting. Note that statement-a will be executed only if the 
values of all three expressions are true. Thus, the preceding example is equivalent to: 

IF expression-1 AND expression-S AND expression-3 
THEN statement -a; 

Notice that the preceding example of nesting does not have an ELSE part. When 
using nested IF statements, it is important to understand the following rule of PL/M: 

• A set of nested IF statements can have only one ELSE part, and it belongs to the 
innermost (that is, the last) of the nested IF statements. 

This rule could also be restated as follows: 

• When an IF statement is nested within the THEN part of an outer IF statement, 
the outer IF statement may not have an ELSE part. 

For example, the construction: 

IF expression-1 THEN 

IF expression-S THEN statement-a 
ELSE statement-b'-, 

is legal and means that if the values of both expression-1 and expression-2 are true, 
then statement-a will be executed. If the value of expression-1 is true and the value of 
expression-2 is false, then statement-b will be executed. If the value of expression-1 
is false, neither statement-a nor statement-b will be executed, regardless of the value 
of expression-2. 

The preceding construction is equivalent to: 

IF expression-1 THEN 
DOi 

IF expression-S THEN statement-a'-, 
ELSE statement-b'-, 

END i 

This construction is much more readable and offers less opportunity for error. 

If the intention is for the ELSE part to belong to the outer IF statement, then the 
nesting must be done by means of a DO block: 

IF expression-1 THEN 

DOn 

IF expression-S THEN statement-a'-, 

end; 

ELSE statement-b'-, 



Flow Control Statements 



Note that the meaning of this construction differs completely from the previous one. 



Finally, consider the following: 

IF expression-1 THEN 

IF expression-S THEN 

IF expression-3 THEN statement-a\ 
ELSE statement-b\ 
ELSE statement-c\ /* illegal statement */ 

ELSE statement-d\ /* illegal statement */ 



This construction is illegal because only one ELSE part is allowed. If the intention is 
for the ELSE parts to match the IF parts as indicated by the indenting, the nesting 
must be done with DO blocks, as follows: 

IF expression-1 THEN 
DOi 

IF expression-3 THEN 

do; 

IF expression-3 THEN statement-a'i 
ELSE statement-b'-, 

END; 

ELSE statement-c'-, 

end; 

ELSE statement-d'i 



6.3.2 Sequential IF Statements 

Consider the following example. An ASCII-coded character is stored in a BYTE 
variable named CHAR. If the character is an A, statement-a should be executed. If 
the character is a B, statement-b should be executed. If the character is a C, statement- 
c should be executed. If the character is not A, B, or C, statement-x should be exe- 
cuted. The code for doing this could be written as follows, using IF statements that 
are completely independent of one another: 

IF CHAR = 'A' THEN statement-a'-, 

IF CHAR = ' B ' THEN statement-b; 

IF CHAR = 'C THEN statement-c'-, 

IF CHAR <> 'A' AND CHAR <> 'B' and CHAR <> *C' THEN statement-x'-, 

This sequence is inefficient because all four IF statements (six tests in all) will be 
carried out in every case, which is wasteful when one of the earlier tests succeeds. 
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A must be tested for in all cases. However, B needs to be tested only if the test for A 
fails and C needs to be tested only if both previous tests fail. Finally, if the tests for A, 
B, and C all fail, no further tests are needed and statement-x must be executed. To 
improve the code, rewrite it as follows: 

IF CHAR = 'A' THEN statement-a\ 

ELSE IF CHAR = 'B' THEN statement-b'-, 

ELSE IF CHAR = 'C THEN statement-c\ 
ELSE statement-x'i 

Notice that this sequence is not a case of nested IF statements as described in the 
preceding section. IF statements are nested only when one IF statement is inside the 
THEN part of another. In the next example, IF statements are inside the ELSE parts 
of other IF statements. This construction is called sequential IF statements. It is 
equivalent to the following: 

IF CHAR = 'A' THEN statement-a; 
ELSE DOi 

IF CHAR = ' B ' THEN statement-b'-, 
ELSE DOi 

IF CHAR = '€' THEN statement-c\ 
ELSE statement-x--, 

END i 

END i 

Sequential IF statements are useful whenever a set of tests is to be made, but the 
remaining tests should be skipped whenever one of the tests succeeds. This construc- 
tion works in such cases because all the remaining tests are in the ELSE part of the 
current test. 

6.4 GOTO Statements 

A GOTO statement alters the sequential order of program execution by transferring 
control directly to a labeled statement. Sequential execution then resumes, beginning 
with the target statement. The GOTO statement has the following form: 

GOTO label 

For example: 

GOTO ABORT i 

The appearance of label in a GOTO statement is called a label reference not a label 
definition. 

The reserved word GOTO can also be written GO TO, with an embedded blank. 
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For reasons discussed in Chapter 7, GOTO statements are restricted. The only possi- 
ble GOTO transfers are the following: 

• From a GOTO statement in the outer level of some block to a labeled statement in 
the outer level of the same block. 

• From a GOTO statement in an inner block to a labeled statement in the outer level 
of an enclosing block (not necessarily the smallest enclosing block). However, if 
the inner block is a procedure block, the transfer can only be to a statement in the 
outer level of the main program module. 

• From any point in one program module to a labeled statement in the outer level 
of the main program module. To jump to such a label, the label must be declared 
to have extended scope, (i.e., declare it PUBLIC in the main module and EX- 
TERNAL in the module containing the GOTO). 

The use of GOTOs is necessary in some situations. However, in most situations where 
control transfers are desired, the use of an iterative DO, DO WHILE, DO CASE, IF, 
or a procedure activation (see Chapter 8) is preferable. Indiscriminate use of GOTOs 
will result in a program that is difficult to understand, correct, and maintain. 

6.5 The CALL and RETURN Statements 

The CALL and RETURN statements are mentioned here only for completeness, 
since they control the flow of a program. However, they are discussed in detail in 
Chapter 8. 

The CALL statement is used to activate an untyped procedure (one that does not 
return a value). 

The RETURN statement is used within a procedure body to cause a return of control 
from the procedure to the point from which it was activated. 
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This chapter explains the meaning of outer level and the concept of scope, including 
the use of the linkage attributes, PUBLIC and EXTERNAL. 

The outer level of a block means statements (or labels) contained in the block but not 
contained in any nested blocks. The term exclusive extent also has this meaning. The 
inner level, or inclusive extent, includes this outer level and all nested blocks as well. 

A block at the same level as another block means that both blocks are contained by 
exactly the same outer blocks. 

The scope of an object means those parts of a program where its name, type, and 
attributes are recognized (i.e., handled according to a given declaration). An object 
means a variable, label, procedure, or symbolic (named) constant (i.e. , a compilation 
constant or execution constant as discussed in Chapter 3). A program is the complete 
set of modules that are ultimately executed as a unit. 

These definitions are explained further in the following sections. 



As shown throughout this manual, PL/M is a block-structured language that enables 
design implementation for problem solving, data processing, and hardware control. 

PL/M is used to create blocks of code containing declarations followed by executable 
statements. These blocks are ordered and nested in such a way as to simplify and 
clarify the flow of data and control. (See Appendix B for maximum block nesting.) A 
collection of these blocks that performs a single function, or a small set of related 
functions, is usually compiled as one module, as discussed in Chapter 1 . 

Beyond the advantages of modularity, simplicity, and clarity, the nesting of blocks 
serves another very basic purpose: names declared at an outer level are known to all 
statements of all nested blocks as well. 
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A new meaning can be declared for any such name within a nested simple DO or 
procedure block, thereby cutting off its earlier meaning for this block. But if this 
option is not chosen, its meaning is established by a single declaration at an outer 
level. (The only objects that do not require declarations prior to use are labels and 
reentrant procedures.) 

In Figure 7-1 , everything inside the solid line constitutes the inclusive extent of block 
MMM (in this case, module MMM). KK is known throughout this block, including 
all nested blocks. 



MMM : 



DOi 

DECLARE RECORD (12fl) STRUCTURE 
(KEY BYTE-, 
INFO UORD) ^ 
DECLARE CURRENT STRUCTURE 
(KEY BYTE n 
INFO WORD) i 
KK BYTE i 



/♦Beginning of module*/ 



DECLARE 
KK = 157 



/* Instructions here would read in data- */ 



SORT: 



DOi 

DECLARE 
DO JJ = 



(JJ-,11) INTEGER 'i 

I TO 157i 

CURRENT. KEY = RECORD ( J J ) ■ KE Y i 
CURRENT. INFO = RECORD ( J J ). INFO =, 

II = JJi 



FIND: 



DO WHILE II > □ AND 

RECORD(II-l) - KEY > CURRENT . KEY =, 
RECORD (II) . KEY = RECORD ( II-l) . KEY =, 
RECORD(II) -INFO = RECORD ( II- 1 ). INFO i 
II = II-ln 
END FIND i 



RECORD(II) -KEY = CURRENT • KEY i 
RECORD(II) -INFO = CURRENT • INFO =, 
END i 

END SORT; 



/* Instructions here would write out data from the records- */ 
END MMMi /* End of module */ 

Figure 7-1 Inclusive Extent of Blocks 
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Everything inside the dashed line constitutes the inclusive extent of block SORT. JJ 
and II are known throughout this block, but not outside it. JJ and II are not known 
before the label SORT or after the END SORT statement. 

Everything inside the dotted line constitutes the inclusive extent of block FIND. Since 
this is not a simple DO or procedure block, declarations are not allowed. All prior 
declarations shown are available for use within FIND. 

In Figure 7-2, the shaded area is the exclusive extent (the outer level) of block SORT. 
The unshaded area within SORT is the exclusive (and inclusive) extent of block 
FIND. To the instructions within the FIND block, SORT'S exclusive extent is an 



MM 11: DO; /*Beginning of module*/ 

DECLARE RECORD <12fl) STRUCTURE 

(KEY BYTE -i 

INFO WORD); 
DECLARE CURRENT STRUCTURE 

(KEY BYTE-, 

INFO WORD) \ 
DECLARE KK BYTE ; 
KK = 127^ 

/* Instructions here would read in data- */ 



SORT : 



DECLARE ( JJ-,11) II-. 
DO J J - 1 TO 127; 

T.KEY = RECORD ( J J ) -KEY; 
CURRENT. INFO » Ri 05 

, 11 * 

FIND : 



DO WHILE II > □ AND 

RECORD(II-l) -KEY > CURRENT. KEY; 
RECORD ( II) ■ KEY = RECORD ( II-l )■ KEY ; 
RECORD (II) ■ INFO = RECORD ( II-l )■ INFO ; 
II = II-l; 
END find; 



RECORD ( 

RECORD(II) • INFO = 
END; 

, _ , 



/* Instructions here would write out data from the records- */ 
END MMM; /* End of module */ 



Figure 7-2 Outer Level of Block SORT 
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outer level. The outermost level (or module level) is the area outside the shaded area 
enclosing the SORT block. 

7,1 .1 Restrictions on Multiple Declarations 

In any given block, a known name cannot be redeclared at the same level as its 
original declaration. A new declaration is permitted inside a nested simple DO or 
procedure block, where it automatically identifies a new object despite the existence 
of the same name at a higher level. The new object will be the only one known by this 
name within its block, and it will be unknown outside its block, where the prior name 
maintains its meaning. These observations also apply when a name is redeclared in 
another block at the same level as the block containing the original declaration. 

When a name is declared only in a separate block at the same level, there is no way to 
access it except in that block where it is declared. The definition is not at an outer 
level to the current block. Any local declaration that is supplied establishes a new 
separate object whose values bear no relation to those of the other. 

The reason for these rules, as for many in programming, is that there must be no 
ambiguity about what address/location is meant by each name in the program. The 
preceding declaration rules give freedom to choose names appropriate to a given 
block, without interfering with exterior uses of them. But when a name is redeclared, 
its outer-level meaning is inaccessible until execution exits the block containing the 
new declaration. For example: 

A: DOn 

DECLARE X-i Yi Z BYTE i 

LJ! X = 1* 

Y = X i 
Z = Xn 

B: DOi 

DECLARE X-i Y BYTEi 
X = 3=, 

Y = I* 
L2: Z = Xn 

END En 

L3: /* At this pointn X = 5 n Y=5 n Z = 3-> because the value of */ 

/* the redeclared X was used to fill Z */ 

/* If statement LS were outside the loop labeled then Z */ 
/* would be 5 because the outer X value would be used */ 
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7.2 Extended Scope: The PUBLIC and EXTERNAL 
Attributes 



These attributes permit the scope of names to be extended for all objects except 
modules; a module name cannot be declared with either attribute. 

To extend the scope means to make the names available for use in modules other than 
the one where they are defined. (The names are already available to nested blocks in 
this module.) To be specific, this includes names for variables, labels, procedures, 
and execution constants. 

For example, the statement: 

DECLARE FLAG BYTE PUBLICS 

causes a byte named FLAG to be allocated, and its address made known to any other 
module where the following declaration occurs: 

DECLARE FLAG BYTE EXTERNAL} 

Similarly, if one module has a procedure declaration block that begins: 

SUMMER: PROCEDURE (A->B) WORD PUBLICS 
DECLARE (A-.B) BYTE i 

/* other declarations can go here */ 
/* executable statements go herei */ 
/* defining the procedure */ 

END SUMMER \ 

then any other module may invoke SUMMER if it first declares: 

SUMMER: PROCEDURE t A -, B ) WORD EXTERNAL; /* A i B can be any names */ 
DECLARE (A-.B) BYTE; /* but these names must match them */ 
/* and each type must match its public definition */ 

END summer; 

The use of PUBLIC and EXTERNAL must follow a strict set of rules to prevent 
ambiguity of location or definition. These rules are as follows: 

1, These attributes can be used only in a declaration at the outermost level of a 
module (i.e., never in a nested block). 

2. Only one can appear in any declaration, no more than once. Thus: 

DECLARE ZETA BYTE PUBLIC EXTERNAL ; /* error */ 

DECLARE RHO WORD PUBLIC PUBLIC ; /* error */ 

and similar constructs are all invalid. 
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3. Names can be declared PUBLIC, no more than once. The PUBLIC declaration is 
the defining declaration: the address it creates is used in each procedure or mod- 
ule where the same name is declared EXTERNAL. Do not create more than one 
PUBLIC address for any name. 

4. Names can be declared EXTERNAL only if they are also declared PUBLIC in a 
different module of the program. The EXTERNAL attribute is essentially a re- 
quest to use a PUBLIC address. An EXTERNAL without a PUBLIC is a dead 
letter. Lack of a definition elsewhere will result in a link-time error. 

5. Where the name is declared EXTERNAL, it must be given the same type as 
where it is declared PUBLIC. Any contradiction of type would violate the inten- 
tion to use the location(s) and content(s) defined elsewhere. If the name is de- 
clared PUBLIC and has the DATA attribute, all EXTERNAL declarations must 
also use DATA, but cannot assign a value to the constant being declared. 

6. Similarly, names declared EXTERNAL must not be given a location (using the 
AT clause), or an initialization (using DATA or INITIAL). Such usage would 
contradict the fact that names are being defined in another module. However, in 
the module where this name is declared PUBLIC, the use of AT, DATA (with 
initialization values present), or INITIAL is allowed. 

7. Neither PUBLIC nor EXTERNAL can be applied to a name that is based. For 
example: 

DECLARE PTR1 POINTER i 
DECLARE VI BASED PTR1 PUBLIC; 

is invalid. The reason: by definition, VI has no home of its own; its location is 
always determined by PTR1 . Thus, to declare VI PUBLIC or EXTERNAL does 
not permit the correct assignment of addresses. PTR1, on the other hand, always 
contains the current address of VI. Declaring the base, in this case PTR1, to be 
PUBLIC or EXTERNAL is always permissible since it permits valid results. 

NOTE 

The PL/M compiler will generate external records only for items that are 
actually referenced in the program. 

8. When extending the scope of a name with the PUBLIC attribute and DATA or 
INITIAL, the placement in the DECLARE statement is critical. PUBLIC must 
be placed after the type declaration and before the DATA or INITIAL attribute. 
For example: 

DECLARE a$p BYTE PUBLIC INITIALS); 

(Additional restrictions on the use of PUBLIC and EXTERNAL procedures are 
described in Chapter 8.) 
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Following these rules will enable consistent and reliable execution of programs using 
names with extended scope. A PUBLIC definition occurring in one module will then 
be used by all related references to that name in separate modules; that is, references 
which declare the name EXTERNAL. The following diagram illustrates this: 



MODI = 


DO i 




DECLARE VI BYTE PUBLIC ; 




• 

END MODI; 


HODS : 


DOn 




DECLARE VI BYTE EXTERNALS 




(3(34: PROCEDURE PUBLIC; 




END (3(34^ 




END MODS; 



Both references to VI will use the same definition (location) for VI, namely, the 
definition in module MODI . Similarly, if any module needed to call procedure QQ4, 
it would first need a declaration like this: 

(3(34 : PROCEDURE EXTERNAL; 
END (3(34; 

so that a subsequent CALL QQ4 would correctly pass control to that procedure in 
MOD2. 

7.3 Scope of Labels and Restrictions on GOTOs 

Labels are subject to exactly the same rules of scope previously discussed. 

A label is unknown outside the block where it is declared. As discussed in Chapter 1 , 
a label is either declared explicitly at the beginning of a simple-DO or procedure 
block, or the compiler considers it to be declared there as soon as it is defined by use 
anywhere in the block. Therefore, the discussion of what names are known in which 
blocks applies directly to labels as well as to other names. 

The label on a block is not part of the block it names. For example, the name on the 
DO enclosing the module itself is not part of the DO; it merely names it. For nested 
blocks, a label is again not part of the block it names, but belongs instead to the outer 
level as part of that first enclosing block. 
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If a name used as a label on a block is defined inside that block, it will name a new 
item, be it label, variable, or constant. There will be no confusion with the outer label 
name. This fact leads to important restrictions on the use of the GOTO statement: 

1 . It is impossible for a GOTO to transfer control from an outer block to a labeled 
statement inside a nested block. 

2. Moreover, a GOTO can transfer control from one block to another in the same 
module only if the target block enclosed the one containing the GOTO (and only 
if the name of that target label is not declared in the nested block). 

Furthermore, a label with the PUBLIC attribute is permitted only in the main mod- 
ule. This has the interesting consequence of forcing all other transfers of control 
(i.e., those not involving a return to the main module) to use procedure calls. This 
favors the development of orderly, modularized, traceable programs. 

Only four GOTO transfers are possible; these are as follows: 

1 . Fr om one point in a block to another statement also in the same level of the same 
block. 

2. From an inner, nested DO-block (not a nested procedure) to a statement in the 
outer level of any enclosing block. 

3. From a procedure to a statement in the outer level of the main program in the 
same module. 

4. To a main-program label that is declared PUBLIC, from any point in any module 
that declares that label EXTERNAL. 

(Recall that only labels at the outer level of a main program can be declared 
PUBLIC.) 

Given the program structure and declarations shown in Figure 7-3, the only valid 
GOTO transfers are shown in Figure 7-4. A single-headed arrow means the transfer is 
valid only in the direction shown. A double-headed arrow means that a GOTO can be 
used in either direction. 

Figure 7-4 illustrates legal GOTO transfers that are the only transfers permitted 
among the given labels in Figure 7-3. 
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HAIN : DOn 

DECLARE (LAB33-, LAB77) LABEL PUBLICS 
DECLARE IT BYTEi 



LAB33: ■ ■ ■ 

DOi 



END: 



L.AB77: 



DO WHILE IT > 0= 



END: 



END MAIN i 
MODI: DOn 

DECLARE ( L AB33 n L AB77 ) LABEL EXTERNAL i 
Pi: PROCEDURES 

L 1 ' * ' • T 

DOi 

DECLARE KO BYTE i 
P5: PROCEDURE i 



LE : 



END P2i 
END"-, 
Lis i 



END Pin 

END MODli 

Figure 7-3 Sample Program Modules Illustrating Valid GOTO Usage 
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MODE: DO} 



DECLARE (LAB33-.LAB77) LABEL EXTERNAL : 
P4: PROCEDURE } 



LS: 



L7: • 



DO} 

Lb: • • • I 



END} 



■ ■ 1 



END PM} 

L A ■ • • - n 

END I10DE} 



Figure 7-3 Sample Program Modules Illustrating Valid GOTO Usage (continued) 
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L2 



LAB33 

OR 
LAB77 



-« L6 »-| 



L7 



L3 




L1 





121636-1 

Figure 7-4 Sample Program Modules Illustrating Valid GOTO Transfers 
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PROCEDURES 

A procedure is a section of PL/M code that is declared without being executed, and 
then activated from other parts of the program. A function reference or CALL state- 
ment activates the procedure, even if it is physically located elsewhere. Program 
control is transferred from the point of activation to the beginning of the procedure 
code, and the code is executed. Upon exit from the procedure code, program control 
is passed back to the statement immediately after the point of activation. 

The use of procedures forms the basis of modular programming. It facilitates making 
and using program libraries, eases programming and documentation, and it reduces 
the amount of object code generated by a program. The following sections review 
how to declare and activate procedures. 

8.1 Procedure Declarations 

A procedure must be declared, just as variables must be declared. Thereafter, any 
reference to a procedure must occur within the scope defined by the procedure 
declaration. Also, a procedure cannot be used (called, or invoked in an expres- 
sion) until after the END statement of the procedure declaration (unless reen- 
trant, see Section 8.5). 

A procedure declaration consists of three parts: a PROCEDURE statement, a se- 
quence of statements forming the procedure body, and an END statement. 

The following is a simple example: 

DOORSCHECK: PROCEDURE \ 

IF FR0NT$D00R$L0CKED AND SIDESDOORSLOCKED THEN 
CALL POUER^ON^ 

ELSE CALL D00R$AL ARM i 
END D00R$CHECK=, 

where POWER$ON and DOOR$ALARM are procedures declared previously in the 
same program. 
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NOTE 



The name in a PROCEDURE statement has the same appearance as a label 
definition, but it is not considered a label definition, and a procedure name is 
not a label. PROCEDURE statements cannot be labeled. 

The name is a PL/M identifier, which is associated with this procedure. The scope of 
a procedure is governed by the placement of its declaration in the program text, just 
as the scope of a variable is governed by the placement of its DECLARE statement 
(see Chapter 7 for a detailed description). Within this scope, the procedure can be 
activated by the name used in the PROCEDURE statement. 

A procedure declaration, like a DO block, controls the scope of variables as de- 
scribed in Chapter 7. Also, like a simple DO block, a procedure declaration can 
contain DECLARE statements, which must precede the first executable statement in 
the procedure body. 

As in a DO block, the identifier in the END statement has no effect on the program, 
but helps legibility and debugging. If used, it should be the same as the procedure 
name. 

The parameter list and the type are discussed in the following two sections. 



8.1.1 Parameters 

Formal parameters are non-based scalar variables declared within a procedure decla- 
ration; their identifiers appear in the parameter list in the PROCEDURE statement. 
The identifiers in the list are separated by commas and the list is enclosed in paren- 
theses. No subscripts or member-identifiers can be used in the parameter list. 

If the procedure has no formal parameters, the parameter list (including the parenthe- 
ses) is omitted from the PROCEDURE statement. 

Each formal parameter must be declared as a non-based scalar variable in a 
DECLARE statement preceding the first executable statement in the procedure body. 
However, procedure parameters are not stored according to the same rules as other 
declared variables. In particular, do not assume that a parameter is stored contigu- 
ously with other variables declared in the same factored variable declaration. 

When a procedure that has formal parameters is activated, the CALL statement or 
function reference contains a list of actual parameters. Each actual parameter is an 
expression whose value is assigned to the corresponding formal parameter in the 
procedure before the procedure begins to execute. 
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For example, the following procedure takes four parameters, called PTR, N, LOWER, 
and UPPER. It examines N contiguously stored BYTE variables. The parameter PTR is 
the location of the first of these variables. If any of these variables is less than the 
parameter LOWER or greater than the parameter UPPER, the ERRORSET procedure 
(declared previously in the program) is activated: 

RANGESCHECK: PROCEDURE (PTR -, N -, LOWER-, UPPER); 

DECLARE PTR POINTER ; 

DECLARE (N-, LOWER-, UPPER-, I) BYTE"-, 

DECLARE ITEM BASED PTR(l) BYTE; 

DO I = TO N - 1; 

IF (ITEM(I) < LOWER) OR (ITEIKI) > UPPER) 
THEN CALL ERRORSET ; 

/* ERRORSET is a procedure declared previously */ 

end; 

end rangescheck; 

Notice that the array ITEM is declared to have only one element. Since it is a based 
array, a reference to any element of ITEM is really a reference to some location 
relative to the location represented by PTR. In writing the procedure RANGE 
$CHECK, a dimension specifier that is any arbitrary number greater than zero must 
be supplied for ITEM so that references to ITEM can be subscripted. But it does not 
matter what the dimension specifier is (1 is arbitrarily used here). 

Having made this declaration, suppose that 25 variables are stored contiguously in an 
array called QUANTS. To check that all of these variables have values within the 
range defined by the values of two other BYTE variables, SMALL and LARGE, 
write: 

CALL RANGESCHECK OflUANTS-, 55-, SHALL-, LARGE); 

When this CALL statement is processed, the following sequence occurs: 

• The four actual parameters in the CALL statement (@ QUANTS, 25, SMALL, 
and LARGE) are assigned to the formal parameters PTR, N, LOWER, and 
UPPER, which were declared within the procedure RANGE$CHECK. Since 
ITEM is based on PTR and the value of PTR is ©QUANTS, every reference to 
an element of ITEM becomes a reference to the corresponding element of 
QUANTS. 
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• The executable statements of the procedure RANGE$CHECK are executed. If 
any of the values are less than the value of SMALL or greater than the value of 
LARGE, the procedure ERRORSET is activated. 

• Finally, control returns to the statement following the CALL statement. 

Notice how the use of a based variable, with the base passed as a parameter, allows 
the procedure to have its own unchanging name (ITEM) for a set of variables which 
may be a different set each time the procedure is activated. 

Parameters are placed on the stack in left-to-right order. The stack grows from higher 
locations to lower locations, so the first parameter occupies the highest position on 
the stack, and the last parameter occupies the lowest position. For more information, 
see Appendix F. 

NOTE 

PL/M does not guarantee the order in which multiple actual parameters will be 
evaluated when the procedure is activated. If one actual parameter changes 
another actual parameter, the results are undefined. This can occur if an ex- 
pression used as an actual parameter contains an embedded assignment or func- 
tion reference that changes another actual parameter for the same procedure. 

8.1.2 Typed Versus Untyped Procedures 

The preceding RANGE$CHECK procedure is an untyped procedure. No type is 
given in the PROCEDURE statement, and it does not return a value. An untyped 
procedure is activated by using its name in a CALL statement, as explained in 
Section 8.2. 

A typed procedure, also called a function, has a type in its PROCEDURE statement: 
an unsigned binary number, signed integer, real number, pointer or selector data 
type. Such a procedure returns a value of this type, which is used in an expression or 
stored as the value of a variable. The procedure is activated by using its name as an 
operand in an expression; this special type of variable reference is called a function 
reference. 

When the expression is processed at run time, the function reference causes the 
procedure to be executed. The function reference itself is then replaced by the value 
returned by the procedure. The expression containing the function reference is then 
evaluated, and program execution continues in normal sequence. 

Like an untyped procedure, a typed procedure can have parameters. They are han- 
dled as described in the previous section. 
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NOTE 



The body of a typed procedure can contain a RETURN statement with an 
expression, as explained later in this chapter. 

The body of a typed procedure can contain code (such as an assignment state- 
ment) that changes the value of some variable declared outside the procedure. 
This is called a side effect. 

Recall that PL/M does not guarantee the order in which operands in an expres- 
sion are evaluated. Therefore, if a function used in an expression changes the 
value of another variable in the same expression, the value of the expression 
depends on whether the function reference or the variable is evaluated first. 

If the analysis of the expression does not force one of these operands to be 
evaluated before the other, then the value of the expression is undefined. 

This situation can be avoided by using parentheses to segregate any typed pro- 
cedure that has a side effect, or by using this procedure in an assignment state- 
ment first to create an unambiguous sequence. 



8.2 Activating a Procedure — Function References and 
CALL Statements 

The two forms of procedure activation depend on whether the procedure is typed or 
untyped. An untyped procedure is activated by means of a CALL statement, which 
has the form: 

CALL name'-, 

or 

CALL name (.parameter list)\ 

For example: 

CALL REORDER ( 3RANK$T ABLE -, 3 ) \ 

(An alternate form of the CALL statement is discussed later.) 

A typed procedure is activated by means of a function reference, which is an operand 
in an expression. A function reference has the form: 
name 

or 

name (.parameter list) 
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This occurs as an operand in an expression, as in the following example: 
TOTAL = SUBTOTAL + SUM$ ARRAY ( 3ITEHS -i COUNT ) i 

where SUM$ ARRAY is a previously declared typed procedure. The value added to 
SUBTOTAL will be the value returned by SUM$ARRAY using the actual parameters 
(©ITEMS, COUNT). 

In both forms of procedure activation, the elements of the parameter list are called 
actual parameters to distinguish them from the formal parameters of the procedure 
declaration. At the time of activation, each actual parameter is evaluated and the 
result is assigned to the corresponding formal parameter in the procedure declara- 
tion. Then, the procedure body is executed. Any PL/M expression may be an actual 
parameter if its type is the same as that of the corresponding formal parameter. 

The actual parameter list in a procedure activation must also match the formal param- 
eter list in the procedure declaration. That is, it must contain the same number of 
parameters of the same type (except as described in the next paragraph) in the same 
order. If the procedure is declared without a formal parameter list, then no actual 
parameter list can be used in the activation. 

As in expression evaluation and assignment statements (see Chapter 5), a few type 
conversions are performed automatically when necessary in activating and returning 
from a procedure. The built-in explicit type conversion procedures described in 
Chapter 9 can also be used to force the value of an expression to a desired type. 

8.2.1 Indirect Procedure Activation 

The CALL statement, in the form shown in the preceding section, activates an un- 
typed procedure by its name. It is also possible to activate an untyped procedure by 
its location. This is done by means of a CALL statement with the form: 

CALL identif ier[-member-identi f ier] [ (.parameter 1 i st ) ]i 

The identifier cannot be subscripted; however it can be a structure reference. The 
identifier must be a fully qualified POINTER or WORD type variable reference for 
PL/M-86 and PL/M-286, and a fully qualified POINTER, OFFSET, or WORD type 
variable reference for PL/M-386. Its value is assumed to be the location of the entry- 
point of the procedure being activated. 
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PL/M-86/286 

I 



NOTE 

Calls through 32-bit POINTERS will be translated into long calls whereas calls 
through 16-bit WORDs or POINTERS (in the SMALL case) will be translated 
into short calls (relative to the current code segment). The compiler will issue a 
warning if the wrong addressing type is used to gain a procedure address for 
later indirect calls. 

end 

— PL/M-86/286 




NOTE 

Calls through 48-bit POINTERS will be translated into long calls whereas calls 
through 32-bit OFFSETS, WORDs, or POINTERS (in the SMALL case) will 
be translated into short calls (relative to the current code segment). 

The identifier for the indirect procedure activation cannot be an HWORD. 
Therefore, all variables used for indirect calling in programs that are recom- 
piled from PL/M-286 and use the WORD 16 control should have DWORD, 
OFFSET (or ADDRESS) data types. 



end 



A normal CALL uses the name of the procedure; the compiler checks to make sure 
that the correct number of parameters is supplied and performs automatic type con- 
version on the actual parameters. 

When the CALL statement uses a location, the compiler does not check the number 
of parameters or perform type conversion. However, type conversion is performed if 
the actual argument is a constant expression. The constant expression is evaluated in 
unsigned context, as described in Section 5.6. If the number of parameters is wrong 
or if an actual parameter is not of the same type as the corresponding formal parame- 
ter, the results are unpredictable. 
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8.3 Exit from a Procedure: The RETURN Statement 

The execution of a procedure is terminated in one of three ways: 

• By execution of a RETURN statement within the procedure body. A typed pro- 
cedure must terminate with a RETURN statement that has an expression. 

• By executing a GOTO to a statement outside the procedure body. The target of 
the GOTO must be at the outer level of the main program (see Chapter 7). 

• By reaching the END statement that terminates the procedure declaration. 

The RETURN statement takes one of two forms: 
RETURN; 

or 

REITURN expressions 

The first form is used in an untyped procedure. The second form is used in a typed 
procedure. The value of the expression becomes the value returned by the procedure. 
It is evaluated as if it were being assigned to a variable of the same type as used on the 
PROCEDURE statement. 

8.4 The Procedure Body 

The statements within the procedure body can be any valid PL/M statements, includ- 
ing CALL statements as well as nested procedure declarations. 

8.4.1 Examples 

1 . The following is a typed procedure declaration: 

AVG: PROCEDURE ( X ■> Y ) REAL; 

DECLARE (X-.Y) REAL; 
RETURN (X + Y)/S.D; 

END AVG ; 

This procedure could be used as follows: 

SMALL = 3-D; 
LARGE = M-O; 

MEAN = AVG (SMALL-, LARGE); 

The effect would be to assign the value 3.5 to MEAN. 
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2. The following is an untyped procedure: 

AOUT: PROCEDURE (ITEM) i 

DECLARE ITEM WORD i 

IF ITEM >= OFFH THEN COUNTER = COUNTER + li 
RETURN i 

END AOUTi 

Here COUNTER is some variable declared outside the procedure (i.e., it is a 
global variable). This procedure could be activated as follows: 

CALL AOUT (UNKNOWN) ■-, 

If the value of the variable UNKNOWN is greater than or equal to OFFH, the 
value of COUNTER will be incremented. 

3. This example demonstrates an important use of based variables: 

SUMSARRAY: PROCEDURE (PTR-.N) BYTE i 
DECLARE PTR POINTER-, 

ARRAY BASED PTR(l) BYTE i (NiSUfl-iI)BYTEi 

sun = 

BO I = D TO n; 

sun = sun + arraycd; 

END i 

return sun; 

END SUM$ARRAYi 

This procedure returns the sum of the first N + 1 elements (from the zeroth to 
the Nth) of a BYTE array pointed to by PTR. Notice that ARRAY is declared to 
have 1 element. Since it is a based variable, no space is allocated for it. It must be 
declared as an array (with a non-zero dimension) so that it can be subscripted in 
the iterative DO block. The choice of 1 as the constant in the dimension specifier 
is arbitrary and does not restrict the value of N that may be supplied when the 
procedure is activated. 

The procedure could be used as follows to sum the elements of a 100-element 
BYTE array named PRICE, and to assign the sum to the variable TOTAL: 
TOTAL = SUM$ARRAY ( 3PRICE -i ) i 

8.5 The Attributes: PUBLIC and EXTERNAL, 
INTERRUPT, REENTRANT 

The PUBLIC and EXTERNAL attributes can be included in PROCEDURE state- 
ments to give procedures extended scope. Extended scope is discussed in Chapter 7. 
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A procedure declaration with the PUBLIC attribute is called a defining declaration. 
A procedure declaration with the EXTERNAL attribute is called a usage declara- 
tion. Most of the rules for PUBLIC and EXTERNAL appear in Chapter 7. The 
following additional rules apply to the use of the EXTERNAL attribute in a proce- 
dure declaration: 

1 . The EXTERNAL attribute cannot be used in the same PROCEDURE statement 
as a PUBLIC or REENTRANT attribute. Note, however, that the defining decla- 
ration of a procedure may have the REENTRANT attribute. 

2. A usage (EXTERNAL) declaration of a procedure should have the same number 
of parameters as the defining (PUBLIC) declaration. Variable types and dimen- 
sion specifiers should match up in the same sequence in both declarations. The 
names of the parameters need not be the same. Note that a discrepancy between 
the parameter lists in the defining declaration and in a usage declaration will not 
be automatically detected. (See Chapter 1 1 for a description of the TYPE control 
to detect such an error at module linkage time.) 

3. The procedure body of a usage declaration cannot contain anything except the 
declarations of the formal parameters. The formal parameters must be declared 
with the same types as in the defining declaration. 

4. No labels can appear in a usage declaration. 



NOTE 

The PL/M compiler will generate external records only for items that are 
actually referenced in the program. 

For example, the procedure AVG (from example 1 in Section 8.4. 1) can be altered by 
giving it the PUBLIC attribute: 

AVG : PROCEDURE ( X ■> Y ) REAL PUBLIC; 
DECLARE (X-.Y) REAL; 
RETURN (X + Y)/2.D=, 

END A VG ; 

Another module would have a usage declaration, as follows: 

AVG : PROCEDURE (X-.Y) REAL EXTERNAL"-, 
DECLARE (X-.Y) REAL; 

END AVG =i 

Now, in the module with the usage declaration, AVG can be referenced in an execut- 
able statement: 

MIDDLE = AVG (FIRST-, LATEST) ; 

thereby activating the procedure AVG as declared in the first module. 
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8.5.1 Interrupts and the INTERRUPT Attribute 



The INTERRUPT attribute enables definition of a procedure to handle some condition 
signaled by a microprocessor interrupt (e.g., from a peripheral device). A procedure 
with this attribute is activated when the corresponding interrupt signal is received in the 
target system. The PL/M statement CAUSESINTERRUPT (constant) can also be used 
to initiate an interrupt signal (see Chapter 10). 

Note that the following discussion applies only to interrupt procedures; interrupt 
tasks are discussed in Appendix G. 

— PL/M-86 

The INTERRUPT attribute can be used only in declaring an untyped procedure with 
no parameter at the outermost level of a program module. It must be declared PUB- 
LIC or EXTERNAL (and optionally REENTRANT). The form is: 
INTERRUPT n 

where n is any decimal number from to 255. Each number can be used only once in 
a program. Each procedure is referred to as an interrupt procedure. Such a procedure 
is necessary to provide non-default handling of exception conditions arising in 
floating-point arithmetic (see Appendixes F and G). 

end 

— PL/M-86 



— PL/M-286/386 

The INTERRUPT attribute can be used only in declaring an untyped procedure with I 
no parameters at the outermost level of a program module. It must be declared 
PUBLIC or EXTERNAL (and optionally REENTRANT). The form is: 
INTERRUPT 

At build time, an interrupt vector is assigned to each interrupt procedure. 

end 

— PL/M-286/386 



The following discussion of the microprocessor interrupt mechanism clarifies how 
interrupt procedures work. Additional information can be found in Appendix G. 

The microprocessor interrupt mechanism has two states: enabled or disabled. With 
the ENABLE statement, interrupts can take effect. The DISABLE statement prevents 
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interrupts from having any effect. The HALT statement also enables interrupts. (The 
state of the microprocessor interrupt mechanism upon initialization is determined by 
the operating system.) 

When some peripheral device sends an interrupt to the microprocessor CPU, it is 
ignored if the interrupt mechanism is disabled. If interrupts are enabled, the interrupt 
is processed as follows: 

1. The CPU completes any instruction currently in execution. 

2. The CPU sends an acknowledge interrupt signal, then the interrupting device 
sends its interrupt number. 

3. The interrupt mechanism is disabled. This prevents any other device from 
interfering. 

4. Control passes to the interrupt procedure whose number matches the number 
sent by the peripheral device. If no such procedure has been established, the 
results are undefined (since the vector that transfers control may be unini- 
tialized). 

5. When the procedure is through (by executing a RETURN or reaching the END 
of the procedure), the interrupt mechanism is enabled so other devices can be 
serviced, and control returns to the point where the interrupt occurred. 

It is possible (as with other untyped procedures) for the procedure to terminate 
by executing a GOTO with a target outside the procedure in the outer level of 
the main program module. In this case, control will never be returned to the 
point where the program was interrupted, and interrupts will not be enabled 
automatically. 

The following is an example of an interrupt procedure for a system where a periph- 
eral device initiates an interrupt whenever the temperature of a device exceeds a 
certain threshold. The interrupt procedure turns on the annunciator light, updates a 
status word, and returns control to the program: 

HITEUP: PROCEDURE INTERRUPT 1DD PUBLIC; 
CALL ANNUNCIATOR(l) \ 

/* This will result in an output from the microprocessor 
to turn on annunciator light number In the 
high-temperature warning- */ 

ALERT = ALERT OR OOOOOOlOBn 

/* This puts a 1 in one of the bit positions of ALERTn 
which contains a bit pattern representing current alerts • */ 

END HITEMPn 
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— PL/M-86 

8.5.2 Activating an Interrupt Procedure with a CALL Statement 

A procedure with the INTERRUPT attribute can also be activated by a CALL state- 
ment. However, interrupts are not automatically disabled on activation of the proce- 
dure. If interrupts are enabled when the CALL is executed, then unless the procedure 
has a DISABLE statement as its first executable statement, it will run with interrupts 
enabled and should have the REENTRANT attribute (see next section). 

NOTE 

If you use an interrupt procedure that will call another interrupt procedure, the 
length of the stack storage must be extended manually, since the compiler allo- 
cates only enough space to save one procedure. See Appendix G and use the 
program combining sequence. 

An interrupt procedure activated by a CALL statement is like any other procedure so 
activated. 

NOTE 

Unlike PL/M-80, PL/M-86 interrupt routines activated with a CALL statement 
do not alter the interrupt enable status. This means that termination of the 
procedure by means of a RETURN statement or the END statement will not 
automatically enable interrupts. 

Section 9.7.2 describes the built-in function INTERRUPT$PTR, which returns the 
interrupt entry point, given an interrupt procedure name. Section 9.7. 1 also describes 
the built-in procedure SET$INTERRUPT, which sets an interrupt vector given the 
interrupt procedure name and number. 

The CAUSE$INTERRUPT statement causes a software interrupt to the vector speci- 
fied in the statement: 

CAUSESINTERRUPT (constant) •■, I 
where constant is in the range to 255 . 

end 

PL/M-86 



Procedures 



8.5.3 Reentrancy and the REENTRANT Attribute 



With the REENTRANT attribute, a procedure can suspend execution temporarily, 
restart with new parameters, and then later complete the original execution success- 
fully as if there had been no interruption. 

This ability is desirable in two circumstances: (1) if the procedure (PROC1) activates 
itself (called direct recursion), or (2) if the procedure activates another procedure 
(PROC2) that will reactivate PROC1 before PROC1 has finished its original process- 
ing (called indirect recursion). 

Without the REENTRANT attribute, storage for procedure variables is allocated 
statically, in fixed locations within the data segment of the object module. Re- 
entering such a procedure would write over the earlier contents of such locations 
making it impossible to complete the original suspended execution. 

When the attribute REENTRANT is used in declaring a procedure, its variables are 
not stored with other variables in the data section, but are stored on the stack. Thus 
preserved, each set can be used independently by each invocation of the procedure. 

Hence, multiple sets of variables might need to be stored on the stack during recur- 
sive use of such procedures. A stack size must be specified (when combining the 
program module) that is large enough for all such storage needed by all multiple 
invocations that may be active at one time. 

A procedure with the REENTRANT attribute may be activated before it is declared. 
This permits direct recursion, where the procedure activates itself and permits indi- 
rect recursion, where the procedure activates a second procedure and the second 
procedure activates the first, or activates a third procedure, which activates a fourth, 
and so forth, with the result that the first procedure is activated before it terminates. 

The following rules summarize the use of the REENTRANT attribute: 

• Any procedure that can be interrupted and is also activated from within an 
interrupt procedure should have the REENTRANT attribute. 

Note that this may apply to an interrupt procedure that runs with interrupts en- 
abled because it contains an ENABLE statement. If there is any possibility that it 
will be interrupted by its own interrupt, it should have the REENTRANT attri- 
bute. This situation is equivalent to recursion. 

• Any procedure that is directly recursive (activates itself) should have the 
REENTRANT attribute. 
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• Any procedure that is indirectly recursive (activates another procedure and is 
activated itself as a result) should have the REENTRANT attribute. 

• Any procedure that is activated by a reentrant procedure should also have the 
REENTRANT attribute. In other words, if there is any possibility that a proce- 
dure can be activated while it is already running, it should be REENTRANT. 

• The REENTRANT attribute cannot be used in the same declaration as the 
EXTERNAL attribute. (It may be used with the PUBLIC attribute.) 

• The REENTRANT attribute can only be used in a PROCEDURE statement at 
the outer level of a module. 

• A procedure declaration with the REENTRANT attribute cannot have a nested 
procedure declaration. 
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BUILT-IN PROCEDURES, 
FUNCTIONS, AND VARIABLES 

HHHMMlMaMHlMili iny — 

Built-in procedures, functions, and variables are already declared in the PL/M code. 
This makes it unnecessary to write code to perform the particular functions that built- 
ins are designed to perform. The following built-in procedures, functions, and vari- 
ables are discussed in this chapter: 

• LENGTH/LAST/SIZE functions — these functions return information con- 
cerning variables. For example, the SIZE function returns the number of bytes 
occupied by a scalar, array, or structure. 

• Explicit type and value conversion functions — these functions provide explicit 
conversion for types and values. 

• Shift and rotate functions — these functions move bits using a pattern of 8, 16, or 
32 bits. 

• String manipulation procedures and functions — these procedures and functions 
move strings, compare strings, search strings for a match or a mismatch, trans- 
late strings, and set strings to a specified value. 

• Bit manipulation procedures (specific to PL/M-386) — these functions copy (and 
move) a bit string and search bit strings for a set bit. 

• MOVE bytes — this procedure moves a specified number of bytes from one 
location to another. 

• Time delay — this procedure causes a time delay. 

• Lock set — this function enables a software synchronization lock. 

• Lock bit — this function enables a memory location lock. 

• Interrupt procedures (specific to PL/M-86) — these procedures enable the set- 
ting of an interrupt vector and an interrupt-handling procedure entry point. 

• POINTER and SELECTOR functions — these functions enable the manipulation 
of location addresses in the microprocessor's memory. 



9-1 



The identifiers for these built-ins are subject to the rules of scope (described in Chap- 
ter 7). This means that the name of a built-in procedure or variable can be declared to 
have a local meaning (scope) within the program. Within the scope of such a declara- 
tion, the built-in is unavailable. This distinguishes these identifiers from reserved 
words (listed in Appendix A), which cannot be used as identifiers in declarations. 

No built-in procedure can be used within a location reference (e.g., 
@LENGTH(LIST) ). No built-in variable can be used within a location reference, 
except as specifically noted in the following sections. 

9.1 Obtaining Information About Variables 

PL/M has three built-in procedures that take variable names as actual parameters and 
return information based on the declarations of the variables: LENGTH, LAST, and 
SIZE. 

9.1.1 The LENGTH Function 

LENGTH is a built-in WORD function that returns the number of elements in an 
array; it is activated by a function reference with the form: 

LENGTH (variable-ref) 
Where: 

variable-ref must be a non-subscripted reference to an array. 

The array can be a member of a structure; it cannot be an EXTERNAL array using 
the implicit dimension specifier (see Section 3.2. 1). 

The value returned is the number of elements assigned to the array in the declaration 
statement (i.e., the value of the dimension specifier). 

If the array is not a structure member, then the reference must be an unqualified 
variable reference. If the array is a structure member, then the reference is a partially 
qualified variable reference. For example, given the declaration: 

DECLARE RECORD STRUCTURE (KEY BYTE-, 

INFOO) WORD ) i 

LENGTH(RECORD.INFO) is a valid function reference and returns a WORD value 
of 3. 



Built-in Procedures, Functions, and Variables 



If the array is a member of a structure, and that structure is an element of an array, a 
special case arises. Given the declaration: 

DECLARE LIST (M) STRUCTURE (KEY BYTE-, 

INFO (3) WORD):, 

then all of the following function references are correct and return the value 3: 

LENGTH ( LIST ( □ ) • INFO) 
LENGTH (LIST ( 1 ) -INFO) 
LENGTH ( LIST ( 5 ) -INFO) 
LENGTH (LIST ( 3 ) -INFO) 

In other words, the subscript for the array LIST is irrelevant when a member- 
identifier is supplied, because the arrays within the structures are all the same length. 
PL/M has a shorthand form of partially qualified variable reference in the LENGTH, 
LAST, and SIZE function references. For example: 

LENGTH(LIST.INFO) 
is a valid function and returns the value 3. 

9.1.2 The LAST Function 

LAST is a built-in WORD function that returns the subscript of the last element in an 
array. It is activated by a function reference with the form: 

LAST (variable) 
Where: 

variable must be a non-subscripted reference to an array. 

The array can be a member of a structure; it cannot be an EXTERNAL array using 
the implicit dimension specifier (see Section 3.2.1). 

The value returned is the subscript of the last element of the array. For a given array, 
LAST will always be one less than LENGTH. When used with a based variable, 
LAST returns the value assigned in the declaration statement. This is not necessarily 
the. actual value. 

As in the LENGTH function, a shorthand form of partially qualified variable refer- 
ence is allowed in the case where the array is a member of a structure that is also an 
array element. 
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9.1.3 The SIZE Function 



SIZE is a built-in WORD function that returns the number of bytes occupied by a 
scalar, array or structure. It is activated by a function reference with the form: 

SIZE (variable) 
Where: 

variable is a fully qualified, partially qualified, or unqualified reference to any 
scalar, array, or structure. The variable cannot be an EXTERNAL 
declaration that uses the implicit dimension specifier (see Section 
3.2). 

The value returned is the number of bytes required by the variable referenced. When 
used with a based variable, SIZE returns the value assigned in the declaration state- 
ment. This is not necessarily the actual (current) value. 

If the reference is fully qualified, it refers to a scalar, and the value is the number of 
bytes required for the scalar. If the reference is unqualified, it refers to an entire 
structure or array, and the value is the total number of bytes required for the structure 
or array. 

If the reference is partially qualified, it refers either to a structure member that is an 
array or nested structure, or to an array element that is a structure. The value is the 
number of bytes required for the array or structure. 

As in the LENGTH function, a shorthand form of partially qualified variable refer- 
ence is allowed in the case where the array or scalar is a member of a structure and 
the structure is an array element. 

9.2 Explicit Type and Value Conversions 

The functions in this section provide explicit conversion from one data type to an- 
other and from signed values to or from absolute magnitudes. 

Explicit type and value conversion functions are invoked as: 
function-name ( expression ) 

In Tables 9-1 and 9-2, each function name is followed by the expression type ex- 
pected, the purpose of the function, and the nature of the value it returns to the 
expression that invoked it. For each function there is only one possible class of ex- 
pressions (e.g., HIGH accepts only unsigned values) that can be converted. For the 
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type conversions (BYTE, WORD, DWORD, INTEGER, REAL, POINTER, and 
SELECTOR, and additionally, for PL/M-386, OFFSET, HWORD, CHARINT, and 
SHORTINT), the context of the entire expression is always a signed integer value. 
Table 9-1 gives the value and type conversions for PL/M-86 and PL/M-286. Table 
9-2 gives the value and type conversions for PL/M-386. 

— PL/M-86/286 



Table 9-1 Value and Type Conversions for PL/M-86 and PL/M-286 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


LOW 


BYTE 

WORD 

DWORD 


Converts WORD value to 
BYTE value 

Converts WORD value to 
BYTE value 

Converts DWORD value to 
WORD value 


BYTE value unchanged 

Low-order BYTE of 
WORD 

Low-order WORD of 
DWORD 


HIGH 


BYTE 
WORD 

DWORD 


Converts WORD value to 
BYTE value 

Converts DWORD value 


(zero) 

High-order BYTE of WORD 

High-order WORD of 
DWORD 


DOUBLE 


BYTE 

WORD 

DWORD 


Converts BYTE value to 
wuhu value 

Converts WORD value to 
DWORD value 


WORD value, by appending 
8 high-order zero bits 

DWORD value, by append- 
ing 16 high-order zero bits 

DWORD value unchanged 


FLOAT 


INTEGER 


Converts INTEGER value 
to REAL value 


Same value of type REAL 


FIX 


REAL 


Converts REAL value to 
INTEGER value (rounds 
toward zero) 


Same value of type 
INTEGER if within range 
-32768 to +32767; other- 
wise undefined 


INT 


BYTE 
WORD 


Converts unsigned value to 
INTEGER value, interprets 
parameter as positive 


Same value of type 
INTEGER if within range 
-32768 to 32767, other- 
wise undefined 
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PL/M-86/286 — 

(continued) 

Table 9-1 Value and Type Conversions for PL/M-86 and PL/M-286 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


SIGNED 


BYTE 
WORD 


Converts an unsigned 
value to an INTEGER value 


BYTE value is extended 
with 8 high-order zeros 
WORD value unchanged 


UNSIGN 


INTEGER 


Converts an INTEGER 
value to a WORD value 


Signed INTEGER value is 
interpreted as unsigned 
WORD value 


ABS 


REAL 


Converts negative real 
value to positive real value 


Absolute value of parame- 
ter: value unchanged if 
positive, -(value) if nega- 
tive. Result type same as 
parameter type 


IABS 


INTEGER 


Converts negative integer 
to positive integer 


Absolute value of parame- 
ter: value unchanged if 
positive, -(value) if nega- 
tive. Result type same as 
parameter type 


BYTE 


any un- 
signed 
type 

INTEGER 


Converts any unsigned 
type to BYTE 

Converts INTEGER type to 

PVTC 
DT 1 t 


BYTE value, by truncation 
BYTE value, by truncation 




REAL 


Converts any REAL type to 
BYTE 


BYTE (INTEGER (real) ) 




SELECTOR 


Converts SELECTOR to 
BYTE 


BYTE value, by truncation 




POINTER 


Converts offset portion of 
POINTER to BYTE 


BYTE (OFFSET$OF 
(pointer) ) 


WORD 


any un- 
signed 
type 

INTEGER 


Converts any unsigned 
type to WORD 

Converts INTEGER type to 
WORD 


WORD value, by truncation 
or zero extension 

WORD value, by sign 
extension 




REAL 


Converts any real type to 
WORD 


WORD (INTEGER 
(real) ) 
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Table 9-1 Value and Type Conversions for PL/M-86 and PL/M-286 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


WORD 


SELECTOR 


Converts SELECTOR to 


WORD value 


(continued) 




WORD 






POINTER 


Converts offset portion of 
POINTER to WORD 


WORD (OFFSET$OF 
(pointer) ) 


DWORD 


any un- 
signed 
type 


Converts any unsigned 
type to DWORD 


DWORD value, by zero 
extension 




INTEGER 


Converts INTEGER type to 
DWORD 


DWORD value, by sign 
extension 




REAL 


Converts any real type to 
DWORD 


DWORD (INTEGER (real) ) 




SELECTOR 


Converts SELECTOR to 
DWORD 


DWORD value, by zero 
extension 




POINTER 


Converts offset portion of 
POINTER to DWORD 


DWORD (OFFSET$OF 
(pointer) ) 


INTEGER 


any un- 


Converts any unsigned 


INTEGER value, by zero 




signed 


type to INTEGER 


extension or truncation 




type 








INTEGER 


INTEGER value not 
changed 


INTEGER value 




REAL 


Converts any real type to 
INTEGER 


FIX (real) 




SELECTOR 


Converts SELECTOR to 
INTEGER 

1 1 X 1 I— l_ 1 1 


INTEGER value 




POINTER 


Converts offset portion of 
POINTER to INTEGER 


INTEGER (OFFSET$OF 
(pointer) ) 


REAL 


any un- 
signed 
type 


Converts any unsigned 
type to REAL 


REAL (SIGNED 
(unsigned) ) 




INTEGER 


Converts INTEGER type to 
REAL 


FLOAT (signed) 




REAL 




value unchanged 
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PL/M-86/286 — 

(continued) 

Table 9-1 Value and Type Conversions for PL/M-86 and PL/M-286 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


SELECTOR 


any un- 
signed 
binary 
tvDe 


Converts any unsigned binary 
type to SELECTOR 


SELECTOR value, by zero 
extension or truncation 




any 
signed 
integer 
data type 


Converts any signed integer 
datatype to SELECTOR 


SELECTOR value by sign 
extension or truncation. 




POINTER 




Selector portion of the 
POINTER 




REAL 




Cannot be used. 


POINTER 


any un- 
signed 
type 


Converts any unsigned type to 
POINTER 


BUILD$PTR (DS, OFFSET 
(unsigned) ) (DS is selector of 
current data segment) 




INTEGER 


Converts INTEGER type to 
POINTER 


BUILD$PTR (DS, OFFSET 
(signed) ) (DS is selector of 
current data segment) 




SELECTOR 




BUILD$PTR (SELECTOR, 0) 



I Notes: Conversions from REAL to OFFSET, SELECTOR, or POINTER, and vice versa, are not 
allowed. 

end 

PL/M-86/286 — 
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Table 9-2 Value and Type Conversions for PL/M-386 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


LOW 


BYTE 




BYTE value unchanged 




HWORD 


Converts HWORD value to 
BYTE value 


Low-order BYTE of 
HWORD 




WORD or 
OFFSET 


Converts WORD or 
OFFSET value to HWORD 
value 


Low-order HWORD of 
WORD or OFFSET 




DWORD 


Converts DWORD value to 
WORD value 


Low-order WORD of 
DWORD 


HIGH 


BYTE 




zero 




HWORD 


Converts HWORD value to 
BYTE value 


High-order BYTE of 
HWORD 




WORD or 
OFFSET 


Converts WORD or 
OFFSET value to HWORD 
value 


High-order HWORD of 
WORD or OFFSET 




DWORD 


Converts DWORD value to 
WORD value 


High-order WORD of 
DWORD 


DOUBLE 


BYTE 


Converts BYTE valup to 
HWORD value 


HWORD bv aDDendina 8 
high-order zero bits 




HWORD 


Converts HWORD value to 
WORD value 


WORD, by appending 16 
hiah-ordpr 7Pro hit*? 




WORD or 
OFFSET 


Converts WORD or 
OFFSET value to DWORD 
value 


DWORD, by appending 32 
high-order zero bits 




UWUnU 




DWORD value unchanged 


FLOAT 


CHARINT 

SHORTINT 

INTEGER 


Converts signed integer 
value to REAL value 


Same value of type REAL 


FIX 


REAL 


Converts REAL value to 
INTEGER value 


Same value of type 
INTEGER if within range 
-2**31 to +(2**31)- 1 
otherwise undefined 
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(continued) 

, Table 9-2 Value and Type Conversions for PL/M-386 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


INT 


BYTE 

HWORD 

WORD 


Converts unsigned binary 
value to INTEGER value, 
interprets parameter as 
positive 


Same value of type 
INTEGER if within range 
-2**31 to +(2**31)-1 
otherwise undefined 


SIGNED 


BYTE 

HWORD 

WORD 


Converts unsigned integer 
value to INTEGER value 


BYTE value is extended 
with 24 high-order zeros 

HWORD value is extended 
with 16 high-order zeros 
WORD value unchanged 


UNSIGN 


CHARINT 
bHUH TINT 
INTEGER 


Converts INTEGER value 
to WORD value 


Signed INTEGER value is 
interpreted as unsigned 
WORD value 


ABS 


REAL 


Converts negative real 
value to positive real value 


Absolute value of parame- 
ter: value unchanged if 
positive -(value) if nega- 
tive. Result type is same as 
parameter type. 


IABS 


CHARINT 

SHORTINT 

INTEGER 


Converts negative integer 
to positive integer 


Absolute value of parame- 
ter: value unchanged if 
positive -(value) if nega- 
tive. If -(value) is out of 
range, result is undefined. 
Result type is same as 
parameter type. 


BYTE 


any 

unsigned 
type 

any signed 
type 

REAL 

SELECTOR 
POINTER 


Converts any unsigned 
type to BYTE 

Converts any signed type 
to BYTE 

Converts any REAL type to 
BYTE 

Converts SELECTOR to 
BYTE 

Converts offset portion of 
POINTER to BYTE 


BYTE value, by truncation 

BYTE value, by truncation 

BYTE (CHARINT (real) ) 

BYTE value, by truncation 

BYTE (OFFSET$OF 
(pointer) ) 
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PL/M-386 

(continued) 



Table 9-2 Value and Type Conversions for PL/M-386 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


HWORD 


any 


Converts any unsigned 


HWORD value, by trunca- 




unsigned 


type to nwunu 


lion or zero extension 




type 








any signed 


Converts any signed type 


HWOHD value, by trunca- 




tvrv> 
type 


to HWORD 


tion or sian extension 




REAL 


Converts any real type to 

nvvUnU 


i i\A/Ann /puAnTiMT 

HWORD (SHORTINT 
(real) ) 




SELECTOR 


Converts SELECTOR to 
MWUnU 


HWORD type, value 
unchanged 




POINTER 


Converts offset portion of 

rUIIN 1 tn 10 nWUnU 


HWORD (OFFSET$OF 
(pointer) ) 


WORD 


any 


Converts any unsigned 


WORD value, by truncation 




unsigned 


type to wuhu 


or zero extension 




type 








any signed 


Converts any signed type 


WORD value, by sign 




lype 


tn WORD 
lu v v unu 






REAL 


Converts any real type to 

WUHU 


WORD (INTEGER (real) ) 




SELECTOR 


Converts SELECTOR to 
WUHD 


WORD value, by zero 
extension 




POINTER 


Converts offset portion of 
POINTER to WORD 


WORD (OFFSET$OF 

/■» M ! »4.A h\ \ 

(pointer) ) 


DWORD 


any 


Converts any unsigned 


DWORD value, by zero 




unsigned 


type to DWORD 


extension 




type 








any signed 


Converts any signed type 


DWUHu value, oy sign 




type 


to DWORD 


extension 




REAL 


Converts any real type to 
DWORD 


DWORD (INTEGER (real) ) 




SELECTOR 


Converts SELECTOR to 
DWORD 


DWORD value, by zero 
extension 




POINTER 


Converts offset portion of 
POINTER to DWORD 


DWORD (0FFSET$0F 
(pointer) ) 
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PL/M-386 — 

(continued) 

, Table 9-2 Value and Type Conversions for PL/M-386 (continued) 



Procedure 


Parameter 


Function 


Result Returned 


Name 


Type 




CHARINT 


any 


Converts any unsigned 


CHARINT value, by 




unsigned 


type to CHARINT 


truncation 




type 








any signed 


Converts any signed type 


CHARINT value, by sign- 




type 


to CHARINT 


extension 




REAL 


Converts any real type to 
CHARINT 


CHARINT (FlX(real) ) 




SELECTOR 


Converts SELECTOR to 
CHARINT 


CHARINT value, by 
truncation 




POINTER 


Converts offset portion of 
POINTER to CHARINT 


CHARINT (OFFSET$OF 
(pointer) ) 


SHORTINT 


any 


Converts any unsigned 


SHORTINT value, by zero 




unsigned 


type to SHORTINT 


extension or truncation 




type 








any signed 


Converts any signed type 


SHORTINT value, by sign 




type 


to SHORTINT 


extension 




REAL 


Converts any real type to 
SHORTINT 


SHORTINT (FIX (real)) 




SELECTOR 


Converts SELECTOR to 
SHORTINT 


SHORTINT value 




POINTER 


Converts offset portion of 
POINTER to SHORTINT 


SHORTINT (OFFSET$OF 
(pointer) ) 


INTEGER 


any 


Converts any unsigned 


INTEGER value, by zero 




unsigned 


type to INTEGER 


extension or truncation 




type 








any signed 


Converts any signed type 


INTEGER value, by sign 




type 


to INTEGER 


extension 




REAL 


Converts any real type to 
INTEGER 


INTEGER (FIX (real) ) 




SELECTOR 


Converts SELECTOR to 
INTEGER 


INTEGER value, by zero 
extension 




POINTER 


Converts offset portion of 
POINTER to INTEGER 


INTEGER (OFFSET$OF 
(pointer) ) 



Built-in Procedures, Functions, and Variables 



PL/M-386 

(continued) 



Table 9-2 Value and Type Conversions for PL/M-386 (continued) 



Procedure 


Parameter 


Function 


Result Returned 


Name 


Type 




REAL 


any 


Converts any unsigned 


REAL (SIGNED 




unsigned 


type to REAL 


(unsigned) ) 




type 
















OFFSET) 








any signed 


Converts any signed type 


rLUAl (signed) 




t\/np 


to REAL 






REAL 




value unchanged 


SELECTOR 


any un- 


Converts any unsigned 


SELECTOR value, by zero 




signed 


binary type to SELECTOR 


extension or truncation 




binary type 








OFFSET 




Current data segment 
selector 




any un- 


Converts any signed inte- 


SELECTOR value by sign 




signed 


ger data type to 


extension or truncation. 




integer 


otLCU IUn 






Uala lyfJ" 








OniMTCD 

POINTER 




Selector portion of the 
POINTER 




REAL 




Cannot be used. 


OFFSET 


any 


Converts any unsigned 


OFFSET, by zero extension 




unsigned 


type to OFFSET 


or truncation 




type 








any signed 


Converts any signed type 


OFFSET, by sign extension 




type 


to OFFSET 






SELECTOR 




zero (0) 




POINTER 




OFFSET$OF (pointer) 
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PL/M-386 — 

(continued) 

, Table 9-2 Value and Type Conversions for PL/M-386 (continued) 



Procedure 
Name 


Parameter 
Type 


Function 


Result Returned 


POINTER 


any 

unsigned 
type 

any signed 
type 

SELECTOR 
OFFSET 


Converts value of any 
unsigned type to POINTER 

Converts value of any 
signed type to POINTER 


BUILD$PTR (DS, OFFSET 
(unsigned) ) (DS is selector 
of current data segment) 

BUILD$PTR (DS, OFFSET 
(signed) ) (DS is selector of 
current data segment) 

BUILD$PTR (SELECTOR, 
0) 

BUILD$PTR (DS, OFFSET) 
(DS is selector of current 
data segment) 



I Notes: Conversions from REAL to OFFSET, or POINTER, and vice versa, are not allowed. 
Under WORD32 (the default), LONGINT is equivalent to INTEGER. ADDRESS is equivalent to 
OFFSET. 

end 

PL/M-386 — 
PL/M-86/286 — 

9.2.1 The PL/M-86/286 LOW, HIGH, and DOUBLE Functions 

In PL/M-86 and PL/M-286, the LOW built-in function converts WORD values to 
BYTE values and DWORD values to WORD values. LOW is activated using the 
following form: 

LOW (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a DWORD value, LOW returns the value of the low-order (least 
significant) WORD of the expression value. If expression has a WORD value, LOW 
returns the value of the low-order (least significant) BYTE of the expression value. If 
expression has a BYTE value, then LOW will return this value unchanged. 
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— PL/M-86/286 

(continued) 

The PL/M-86/286 HIGH built-in function converts WORD values to BYTE values I 
and DWORD values to WORD values. HIGH is activated using the following form: 

HIGH (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a DWORD value, HIGH returns the value of the high-order (most 
significant) WORD of the expression value. If expression has a WORD value, HIGH 
returns the value of the high-order (most significant) BYTE of the expression value. 
If expression has a BYTE value, then HIGH returns a zero. 

The PL/M-86/286 DOUBLE built-in function converts BYTE values to WORD val- 
ues and WORD values to DWORD values. DOUBLE is activated using the following 
form: 

DOUBLE (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a BYTE value, the DOUBLE function appends 8 high-order zero 
bits to convert the expression to a WORD value and returns this WORD value. If 
expression has a WORD value, the DOUBLE function appends 16 high-order zero 
bits to convert the expression to a DWORD value and returns this DWORD value. If 
expression has a DWORD value, the DOUBLE function returns this DWORD value 
unchanged. 

end 

— PL/M-86/286 
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PL/M-386 " 

| 9.2.2 The PL/M-386 LOW, HIGH, and DOUBLE Functions 

The PL/M-386 LOW built-in function converts DWORD values to WORD values, 
WORD or OFFSET values to HWORD values, and HWORD values to BYTE values. 
LOW is activated using the following form: 

LOW (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a DWORD value, LOW returns the value of the low-order (least 
significant) WORD of the expression value. If expression has a WORD or OFFSET 
value, LOW returns the value of the low-order (least significant) HWORD of the 
expression value. If expression has an HWORD value, LOW returns the value of the 
low-order (least significant) BYTE of the expression value. If expression has a BYTE 
value, LOW returns this value unchanged. 

The PL/M-386 HIGH built-in function converts DWORD values to WORD values, 
WORD or OFFSET values to HWORD values, and HWORD values to a BYTE val- 
ues. HIGH is activated using the following form: 

HIGH (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a DWORD value, HIGH returns the value of the high-order (most 
significant) WORD of the expression value. If expression has a WORD or OFFSET 
value, HIGH returns the value of the high-order (most significant) HWORD of the 
expression value. If expression has an HWORD value, HIGH returns the value of the 
high-order (most significant) BYTE of the expression value. If expression has a 
BYTE value, then HIGH will return a zero. 
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— PL/M-386 

(continued) 

The PL/M-386 DOUBLE built-in function converts BYTE values to HWORD values, \ 
HWORD values to WORD values, and WORD or OFFSET values to DWORD 
values. DOUBLE is activated using the following form: 

DOUBLE (expression) 
Where: 

expression has an unsigned binary number data type value. 

If expression has a BYTE value, the DOUBLE function appends 8 high-order zero 
bits to convert the expression to an HWORD value and returns this HWORD value. If 
expression has an HWORD value, the DOUBLE function appends 16 high-order zero 
bits to convert the expression to a WORD value and returns this WORD value. If 
expression has a WORD or OFFSET value, the DOUBLE function appends 32 high- 
order bits to convert it to a DWORD value and returns this DWORD value. If expres- 
sion has a DWORD value, the DOUBLE function returns this DWORD value 
unchanged. 

end 

PL/M-386 



9.2.3 The FLOAT Function 

FLOAT is a built-in REAL function that converts a signed integer data type to a real 
number data type. It is activated by a function reference with the following form: 

FLOAT (expression) 
Where: 

expression is a signed integer data type. 

FLOAT converts the signed integer data type to the corresponding real number data 
type and returns the real number data type. FLOAT can be replaced with REAL 

(expression). 
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9.2.4 The FIX Function 



FIX is a built-in INTEGER function that converts a REAL value to an INTEGER 
value. It is activated by a function reference with the following form: 

FIX (expression) 
Where: 

expression has a REAL value. 

FIX rounds the REAL value to the nearest INTEGER. If both INTEGER values are 
equally near, FIX rounds to the even value. The resulting INTEGER value is then 
returned. 



For example: 

FIXC1.4) /* would result in the INTEGER value In */ 

FIX(-Lfl) /* in -5n */ 

FIXO-S) /* in ^■, and */ 

FlX(b-S) /* in b- */ 



If the result calculated by FIX is not within the implemented range of INTEGER 
values, the result is undefined. 



NOTE 

FIX is affected by the rounding mode, see Section 10.6. The default mode 
(round to the nearest or even value) is used in the previous examples. 

FIX can be replaced with INTEGER (expression). 



9.2.5 The INT Function 



INT is a built-in INTEGER function that converts an unsigned binary data type, 
excluding DWORD, to a signed integer data type. It is activated by a function refer- 
ence with the following form: 

INT (expression) 
Where: 

expression has an unsigned binary data type, excluding DWORD. 

INT interprets the expression value as a positive number and returns the correspond- 
ing INTEGER value. 
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If the result calculated by INT is not within the implemented range of INTEGER 
values, the result is undefined. (See Chapter 5 for ranges for INTEGER values.) 



9.2.6 The SIGNED Function 

For PL/M-86 and PL/M-286, SIGNED is a built-in INTEGER function that con- 
verts a BYTE or WORD value to an INTEGER value. For PL/M-386, SIGNED is 
a built-in INTEGER function that converts a BYTE, HWORD, or WORD value to 
an INTEGER value. SIGNED is activated by a function reference with the follow- 
ing form: 



expression is an unsigned binary number data type, excluding DWORD. 

For PL/M-86 and PL/M-286, if the expression has a BYTE value, it will be extended 
by 8 high-order bits to produce a WORD value. 

For PL/M-386, if expression has a BYTE or HWORD value, it will be extended by 
24 or 16 high-order bits, respectively, to produce a WORD value. 

SIGNED interprets the WORD value as a 16-bit two's-complement number (for 
PL/M-86 and PL/M-286) or a 32-bit two's-complement number (for PL/M-386) and 
returns the corresponding integer value. 

If the highest-order (most significant) bit of the WORD value is a 0, SIGNED inter- 
prets the WORD value as a positive number and returns the corresponding INTEGER 
value. For example: 

SIGNED (□□□□SDDDDSDDDDSDIDDB) 
returns an INTEGER value of 4. 

If the highest-order bit of the WORD value is a 1, SIGNED returns a negative 
INTEGER value whose absolute magnitude is the two's complement of the WORD 
value. For example: 

SIGNED (llllSllllSllllSllODB) 

returns an INTEGER value of -4. 

SIGNED can be replaced by INTEGER (expression). 



SIGNED (expression) 



Where: 
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9.2.7 The UNSIGN Function 



The UNSIGN built-in function converts a signed integer data type to a WORD value. 
It is activated by a function reference with the following form: 

UNSIGN (expression) 
Where: 

expression is a signed integer data type. 
UNSIGN converts the INTEGER value to a WORD value. 

If the INTEGER value is positive, the WORD value will be numerically the same as 
the INTEGER value. However, if the INTEGER value is negative, the WORD value 
will be the two's complement of the absolute magnitude of the INTEGER value. For 
example: 

UNSIGN(-4) 

returns a WORD value of: 

miiim$im$ii0OB 

UNSIGN can be replaced by WORD (expression). 

9.2.8 The Unsigned Binary Data Type Built-in Functions 

The unsigned binary data type built-in functions convert any expression to the speci- 
fied unsigned binary data type. For example, the WORD and DWORD built-in func- 
tions convert any expression to a WORD or DWORD value, respectively. 

The built-in functions are activated with the form: 
built-in (expression) 

Where: 

built-in is the name of the data type to which the given expression is con- 

verted (e.g. , BYTE or WORD). 

expression has any value. 

For example, WORD (INT1) converts the value of INT 1 to a WORD value. 

If expression is an unsigned binary number data type, it is converted by truncation or 
zero extension, if necessary. If expression is a signed integer data type, it is converted 
by truncation or zero extension, if necessary. If expression is a selector data type, it is 
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converted by truncation or zero extension. If expression is a pointer data type, the 
offset portion of the pointer is converted by truncation or zero extension; the selector 
portion of the pointer is discarded. If expression is a real number data type, it is first 
converted to a signed integer using the numeric coprocessor's real to integer conver- 
sion, then the resulting value is converted to the unsigned binary number data type by 
truncation, if necessary. 

9.2.9 Signed Integer Data Type Built-in Function 

The signed integer data type built-in function converts any expression to a signed 
integer data type. 

For example: 

INTEGER (») 

converts the value of D to an INTEGER value within the INTEGER range. 

If expression is an unsigned binary number or selector data type, it is converted by 
truncation or zero extension. If expression is a pointer data type, the offset portion of 
the pointer is converted by truncation or zero extension; the selector portion of the 
pointer is discarded. If expression is a real number data type, it is converted using the 
numeric coprocessor's real to integer conversion. For PL/M-86 and PL/M-286, if 
expression is a signed integer data type, no operation is necessary. 

— PL/M-386 

Specific to PL/M-386, if expression is a signed type, it is converted by sign exten- 
sion. Shorter data types are converted into longer data types by sign extending the 
shorter data type value. Longer data types are converted into shorter data types by 
sign extension of the bits equivalent to the shorter data type. For example, if a 
CHARINT built-in is used to convert an INTEGER value, the least significant 8 bits 
are sign extended and the value returned is guaranteed to be in the CHARINT range. 

end 

PL/M-386 



9.2.10 REAL Built-in Functions 

The REAL built-in function converts an expression to a REAL value. Expressions of 
type SELECTOR, OFFSET, and POINTER cannot be used. The conversion is done 
using the numeric coprocessor's INTEGER to REAL conversion. If the expression is 
an unsigned binary number data type it is zero extended, if necessary, and interpreted 
as a signed value. 
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9.2.11 The SELECTOR Built-in Function 



The SELECTOR built-in function converts any expression (except the real number 
data type) to a SELECTOR value. If expression is any unsigned binary number data 
type, except OFFSET, it is truncated or zero extended to 16 bits. If expression is a 
signed integer data type, it is truncated or sign extended to 16 bits. If expression is of 
type POINTER, the selector portion of the pointer is returned. If expression is of type 
OFFSET, the current data segment selector is returned. Expressions of type REAL 
cannot be used. 

9.2.12 The POINTER Built-in Function 

The POINTER built-in function converts any expression (except the real number 
data type) to a POINTER value. If expression is any unsigned binary number or 
signed integer data type, it is converted to type OFFSET by truncation, zero, or 
sign extension, if necessary. This OFFSET value is combined with the SELECTOR 
value of the current data segment to create the POINTER value. If expression is of 
type SELECTOR, it is combined with an OFFSET value of zero to create the 
POINTER value. Expressions of type REAL cannot be used. 

9.2.13 The OFFSET Built-in Function 

The OFFSET built-in function converts any expression (except the real number data 
type) to an OFFSET value. If expression is any unsigned binary number or signed 
integer data type, it is converted to type OFFSET by truncation, or by zero or sign 
extension. If expression is of type SELECTOR, an OFFSET value of zero is re- 
turned. If the expression is of type POINTER, the offset portion of the pointer is 
returned. ADDRESS values are equivalent to OFFSET. Expressions of type REAL 
cannot be used. 

9.2.14 The ABS and IABS Functions 

The ABS built-in function returns the absolute value of a real number data type. It is 
activated by a function reference with the following form: 

ABS (expression) 
Where: 

expression is a real number data type. 

If the value of expression is positive, ABS returns it unchanged. If the value of 
expression is negative, ABS returns — (expression). 
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The IABS built-in function returns the absolute value of a signed integer data type. It 
is activated by a function reference with the following form: 

IABS (expression) 
Where: 

expression is a signed integer data type. 

If the value of expression is positive, IABS returns it unchanged. If the value of 
expression is negative, IABS returns —(expression). 

9.3 Shift and Rotate Functions 

With the shift and rotate functions, bit patterns can be moved to the right and to the 
left. In a shift, bits moved off one end of the pattern are lost, and zero bits move into 
the pattern from the other end (except in the case of the algebraic shift right function, 
SAR; see Section 9.3.3). In a rotate, bits moved off one end of the pattern are moved 
onto the other end of the pattern. It is not possible to perform a rotate on a signed 
integer algebraic pattern. 

For PL/M-86 and PL/M-286, in shift and rotate operations, a value is handled as a 
pattern of 8 bits (for a BYTE value), 16 bits (for a WORD or INTEGER value), or 32 
bits (for a DWORD value). For PL/M-386, a value is handled as a pattern of 8 bits 
(for a BYTE or CHARINT value), 16 bits (for a HWORD or SHORTINT value), 32 
bits (for WORD, OFFSET, or INTEGER values), or 64 bits (for a DWORD value). 
The pattern is moved to the right or left by a specified number of bits called the bit 
count. 

9.3.1 Rotation Functions 

The type of the rotate left (ROL) and rotate right (ROR) built-in functions depends on 
the type of expression given as an actual parameter. These built-ins are activated by 
function references with the following forms: 

ROL (pattern, count) 
ROR (pattern, count) 

Where: 

pattern and count are expressions using an unsigned binary number data type. 
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If count is any unsigned binary number data type except BYTE, all but the low-order 
bits will be dropped to produce a BYTE value. If the value of count is 0, no rotation 
occurs. 

The value of pattern is handled as an 8-bit, 16-bit, 32-bit, or 64-bit quantity. The type 
of pattern determines which of the unsigned binary number data types is used. This, 
in turn, determines the value of pattern. For example, HQWORD, SHORTINT, and 
WORD are all 16-bit quantities (see Table 3-2). The number of bit positions by which 
pattern is rotated is specified by count. 

The following are examples of the action of these procedures: 

ROR (10 Dill DIB-, 1) returns a value of 11001 HOB 

ROL (lOrJlllOlB-, E ) returns a value of Oil 101 10B 

ROR (HDlDllDlDDllDlDBn 1 ) returns a value of 01001 10101 10101 IB 

9.3.2 Logical-Shift Functions 

The type of the logical-shift left (SHL) and logical-shift right (SHR) built-in func- 
tions depends on the type of the expression given as an actual parameter. SHL and 
SHR are activated by function references with the forms: 

SHL (pattern, count) 
SHR (pattern, count) 

Where: 

pattern and count are expressions using an unsigned binary number data type. 

If count is any unsigned binary number data type except BYTE, all but the 8 low- 
order bits will be dropped to produce a BYTE value. If the value of count is 0, no 
shift occurs. 

The value of pattern can be a BYTE, HWORD, WORD, or DWORD value and the 
value will not be converted. If pattern is a BYTE value, the function will return a 
BYTE value. If pattern is an HWORD value, the function will return an HWORD 
value. If pattern is a WORD value, the function will return a WORD value; if pattern 
is a DWORD value, the function will return a DWORD value. 

The value of pattern is shifted left (by SHL) or right (by SHR), with the bit count 
given by count. 
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A shift operation can force one bit out of the pattern. For example: 

SHLCLDDDSOODlB-il) 
returns 0000$0010B, losing the former high-order bit, and: 

SHRClDOD^DODlBnl) 
becomes 0100$0000B, losing the former low-order bit. 

If the specified pattern and count do not lose information, a shift of one bit position 
has the effect of multiplication by two for a left shift, or division by two for a right 
shift. For example, suppose that VAR is a BYTE variable with a value of eight. This 
is represented as 0000$1000B. SHL(VAR,1) would return 0001$0000B, which repre- 
sents 16, and SHR(VAR.l) would return 0000$0100B, which represents four. 

Casting can be used to ensure that no information is lost in a shift, as in the following 
example: 

SHL(UORD(LIT$MASK) -,3) 

9.3.3 Algebraic-Shift Functions 

The type of the algebraic-shift left (SAL) and algebraic-shift right (SAR) built-in 
functions depends on the type of the expression given as an actual parameter. SAL 
and SAR are activated by function references with the following forms: 

SAL (pattern, count) 
SAR (pattern, count) 

Where: 

pattern is an expression using a signed integer data type. 
count is an expression using an unsigned binary data type. 

If count is any unsigned binary data type except BYTE, all but the 8 low-order bits 
will be dropped to produce a BYTE value. If the value of count is zero, no shift 
occurs. 

For PL/M-386, the type of pattern can be a CHARINT, SHORTINT, or INTEGER 
value. All values are converted to INTEGER before the shift operations, and an 
INTEGER value is returned. 
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For PL/M-86 and PL/M-286, SAL and SAR treat the INTEGER value of pattern as a 
bit pattern. For PL/M-386, SAL and SAR treat the signed value of pattern as a bit 
pattern. This pattern is shifted to the left or to the right. 

In a left shift (SAL), zero-bits move into the pattern from the right (as in SHL and 
SHR). 

In a right shift (SAR), either zero bits or one bits move into the pattern from the left. 
If the original value of pattern is positive, the sign bit (leftmost bit) is a 0, and zero 
bits move in from the left. If the original value is negative, the sign bit is a 1, and one 
bits move in from the left. 



In some instances (as in logical shifts), an algebraic shift of one bit position can 
have the effect of multiplication by two for a left shift or division by two for a right 
shift. For example, suppose that VAL is an INTEGER variable with a value of — 8. 
This value is 1 1 1 1$1 1 1 1$1 1 1 1$1000B. SAL(VAL,1) would return 
111 1S1 1 11$1 1 1 1S0000B, which is -16, and SAR(VAL,1) would return 
1111$1111$1111$1100B, which is -4. 

PL/M-386 

9.3.4 Concatenate Functions 

The concatenate functions (SHLD and SHRD) are built-in WORD double-shift func- 
tions that concatenate two WORD values to form a 64-bit string, shift the concate- 
nated pattern left (SHLD) or right (SHRD) by count bits, and return the destination 
WORD. These built-ins are activated by function references with the following form: 

keyword (high pattern, low pattern, count) 
Where: 

keyword is SHLD or SHRD. 
high pattern is a WORD value. 
low pattern is a WORD value. 

count is a BYTE, HWORD, or WORD value that determines how many 

bits to shift the concatenated pattern. 

SHLD concatenates the bit pattern of the WORD value high pattern with the bit 
pattern of the WORD value low pattern to form a 64-bit string, high pattern is placed 
in the high 32 bits and low pattern is placed in the low 32 bits. The concatenated 
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— PL/M-386 

(continued) 

pattern is shifted left by the number of bits given by count MODULO 32. These I 
operands are taken MODULO 32 to provide a number between and 3 1 by which to 
shift. This has the effect of shifting the high order bits of low pattern into the low 
order bits of high pattern. SHLD returns the high 32 bits of the shifted pattern. 

SHRD concatenates the bit pattern of the WORD value high pattern with the bit 
pattern of the WORD value low pattern to form a 64-bit string, high pattern is placed 
in the high 32 bits and low pattern is placed in the low 32 bits. The concatenated 
pattern is shifted right by the number of bits given by count MODULO 32. These 
operands are taken MODULO 32 to provide a number between and 3 1 by which to 
shift. This has the effect of shifting the low order bits of high pattern into the high 
order bits of low pattern. SHRD returns the low 32 bits of the shifted pattern. 

end 

PL/M-386 



9.4 String Manipulation Procedures and Functions 

The term string is used here in a broader sense than previously, in which string was 
used to refer to a BYTE string. In this section, a string is any contiguously stored set 
of unsigned binary number data type values (excluding DWORD and OFFSET). A 
string can be regarded as if it were an unsigned binary number type (excluding 
DWORD and OFFSET) array, and the array items can be referred to as elements. 

The word index refers to the position of a given element within a string. The index is 
similar to the subscript of an array reference. Thus, the index of the first element of a 
string is 0, the index of the second element is 1, and so on. 

In the following descriptions, the location of a string always means the location of its 
first element. In each string manipulation procedure, the location of a string is speci- 
fied by a parameter called source or destination, which is an expression with a 
POINTER value. The source points to the lowest element. For example, with MOVB 
and MOVW, the lowest element (element 0) is the first element to be processed. With 
MOVRB and MOVRW, the lowest element is the last element to be processed, as 
discussed in the following sections. 

The length of a string is the number of elements it contains. In each string manipula- 
tion procedure, the number of elements to be processed is specified by a parameter 
called count. 
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NOTE 

If the source or destination string address is in SELECTOR or WORD form, 
use the @ operator of a variable based on the address. Otherwise, the built-in 
function BUILDSPTR can be used to construct the pointer-parameter for the 
string built-in. 

For PL/M-86 and PL/M-286, each of the string manipulation procedures described 
in the following sections (except XLAT) is available in pairs, that is, each built-in is 
available for BYTE and WORD strings. 

For PL/M-386, each of the string-manipulation procedures described in the following 
sections (except XLAT) is available in triples, that is, each built-in is available for 
BYTE, HWORD, and WORD strings. 

9.4.1 The Copy String in Ascending Order Procedure 

MOVxx is an untyped procedure that copies a string of length count from one loca- 
tion to another. It is activated by a CALL statement with the following form: 

CALL keyword (source, destination, count); 



Where: 



keyword 



PL/M-86 

MOVB, MOVW 



source and expressions with 
destination POINTER values 

count expression with 

BYTE or WORD 
value 



PL/M-286 

MOVB, MOVW 

expressions with 
POINTER values 

expression with 
BYTE or WORD 
value 



PL/M-386 

MOVB, MOVHW, 
MOVW 

expressions with 
POINTER values 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



The string elements are copied in ascending order (i.e. , element is copied first, then 
element 1, etc.). This order is significant if the source string and the destination 
string overlap. If the value of destination is higher than the value of source, and the 
two strings overlap, elements in the overlap area will be overwritten before they are 
copied. To avoid the overwriting, use MOVRxx instead of MOVxx. 

MOVW performs the same function as MOVB except that MOVW copies a WORD 
string instead of a BYTE string. 
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For PL/M-386, MOVHW performs the same function as MOVB except that 
MOVHW copies an HWORD string. 



9.4.2 The Copy String in Descending Order Procedure 



MOVRxx is an untyped procedure that copies a string of length count from one 
location to another. It is activated by a call statement with the following form: 

CALL keyword (source, destination, count); 



Where: 



keyword 



PL/M-86 

MOVRB, MOVRW 



source and expressions with 
destination POINTER values 

count expression with 

BYTE or WORD 
value 



PL/M-286 

MOVRB, MOVRW 



expressions with 
POINTER values 

expression with 
BYTE or WORD 
value 



PL/M-386 

MOVRB, 

MOVRHW, 

MOVRW 

expressions with 
POINTER values 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value. 



The MOVRB built-in procedure is similar to the MOVB procedure except that the 
elements in the MOVRB source string are copied to the destination string in descend- 
ing order (i.e., element (count-1) is copied first, then element (count-2), and so on, 
with element copied last). This order is significant when the two strings overlap. If 
the value of destination is higher than the value of source, and an overlap exists, 
elements in the overlap area will not be overwritten until they have been copied. 
However, if the value of source is higher than the value of destination, elements in the 
overlap area will be overwritten before they are copied. 

MOVRW performs the same function as MOVRB, except MOVRW copies a WORD 
string instead of a BYTE string. 

For PL/M-386, MOVHW performs the same function as MOVRB except that 
MOVHW copies an HWORD string. 
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NOTE 



If two strings overlap, use a procedure such as the following (written in 
PL/M-86) to make the correct choice between MOVB and MOVRB. This en- 
sures that elements in the overlap area will not be overwritten until after they 
have been copied. 

MOV BYTES: PROCEDURE (SRd DST n CNT ) i 
DECLARE (SRC-, DST) POINTER-, CNT WORD: 
IF SRODST THEN CALL MOVB (SRC-, DST-> CNT ) i 
ELSE CALL MOVRB (SRC-, DST i CNT ) i 

END MOVBYTES i 

This procedure can be activated without the need to consider whether overlap 
may occur or whether source or destination is higher. 



9.4.3 The Compare String Function 



CMPxx is a built-in WORD function that compares two strings of length count . It is 
activated by a function reference with the following form: 

keyword (sourcel, source2, count) 



Where: 

keyword 

sourcel and 
source2 

count 



PL/M-86 

CMPB, CMPW 

expressions with 
POINTER values 

expression with 
BYTE or WORD 
value 



PL/M-286 
CMPB, CMPW 



expressions with 
POINTER values 

expression with 
BYTE or WORD 
value 



PL/M-386 

CMPB, CMPHW, 
CMPW 

expressions with 
POINTER values 

expression with 
BYTE, HWORD, 
OFFSET, or 
WORD value 



CMPB compares two BYTE strings of length count whose locations are sourcel and 
sourcel. 

If every element in the string at sourcel is equal to the corresponding element in the 
string at source2, CMPxx returns a WORD value (OFFFFH for PL/M-86 and 
PL/M-286, and OFFFFFFFFH for PL/M-386. Otherwise, CMPxx returns the index 
(position within the strings) of the first pair of elements found to be unequal. 
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CMPW performs the same as function CMPB except that CMPW compares two 
WORD strings instead of two BYTE strings. 

For PL/M-386, CMPHW performs the same function as CMPB, except that 
CMPHW compares two HWORD strings. 



9.4.4 The Find Element Functions 



FIND is a built-in WORD function that searches a string to find an element that has a 
specified value. It is activated by a function reference of the following form: 

keyword (source, target, count) 



Where: 



PL/M-86 



keyword FINDB, FINDW, 

FINDRB, FINDRW 



source expression with 
POINTER value 

target expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce a 
BYTE or WORD 
value 

count expression with 
BYTE or WORD 
value 



PL/M-286 

FINDB, FINDW, 
FINDRB, FINDRW 



expression with 
POINTER value 

expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce a 
BYTE or WORD 
value 

expression with 
BYTE or WORD 
value 



PL/M-386 

FINDB, FINDHW, 
FINDW, FINDRB, 
FINDRHW, 
FINDRW 

expression with 
POINTER value 

expression with 
BYTE, HWORD, or 
WORD value — the 
high-order bits are 
dropped to produce a 
BYTE, HWORD, or 
WORD value 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



FINDB examines each element of the source string (in ascending order) until it finds 
an element whose value matches the BYTE value of target, or until count elements 
have been searched, with none of them having matched the target. If the search is 
successful, FINDB returns the index of the first element of the string that matches 
target. If the search is unsuccessful, FINDB returns a WORD value. 

For PL/M-386, FINDHW performs the same function as FINDB, except that 
FINDHW searches an HWORD string. If target has a BYTE value, it is extended by 
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8 high-order, O-bits to produce an HWORD value. If target has a WORD value, it is 
truncated by 16 high-order bits to produce an HWORD value. 

FINDW performs the same function as FINDB, except that FINDW searches a 
WORD string. For PL/M-86 and PL/M-286, if target has a BYTE value, it is ex- 
tended by 8 high-order O-bits to produce a WORD value. For PL/M-386, if target has 
a BYTE or HWORD value, target is extended appropriately to produce a WORD 
value. 

FINDRB performs the same function as FINDB, except that FINDRB searches the 
source string in descending order. Thus, if each search is successful, FINDRB re- 
turns the index of the last (highest subscript) element that matches the BYTE value of 
target. FINDRW performs the same function as FINDRB, except that FINDRW 
searches a WORD string (in descending order). 

For PL/M-386, FINDRHW performs the same function as FINDRB, except that 
FINDRHW searches an HWORD string (in descending order). 

9.4.5 The Find String Mismatch Function 

SKIP is a built-in WORD function that searches the BYTE string of length count at a 
specified location (given by source) for the first BYTE value that does not match the 
target BYTE. This search begins with the first BYTE value of the string. The result is 
either a WORD value (OFFFFH for PL/M-86 and PL/M-286, and OFFFFFFFFH for 
PL/M-386) if the string contains only BYTE values equal to the target BYTE, or the 
WORD value will be equal to the index of the first BYTE value not equal to the target 
BYTE. 

The function is activated by a function reference of the following form: 
keyword (source, target, count) 
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Where: 



PL/M-86 



PL/M-286 



PL/M-386 



keyword SKIPB, SKIPW, 

SKIPRB, SKIPRW 



SKIPB, SKIPW, 
SKIPRB, SKIPRW 



SKIPB, SKIPHW, 
SKIPW, SKIPRB, 
SKIPRHW, SKIPRW 



source expression with 



POINTER value 



POINTER value 



expression with 



expression with 
POINTER value 



target 



expression with 
BYTE or WORD 
value 



expression with 
BYTE or WORD 
value 



expression with 
BYTE, WORD, or 
HWORD value 



count 



expression with 
BYTE or WORD 
value 



expression with 



expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



BYTE or WORD 
value 



SKIPW performs the same function as SKIPB, except that SKIPW searches a WORD 
source string to find the first element that does not match the WORD value of target. 

SKIPRB searches a BYTE string of the length specified by count, at the location 
given by source, for the last BYTE value that does not match the target BYTE. This 
search begins with the last BYTE value in the string. The result is a WORD value 
(OFFFH for PL/M-86 and PL/M-286, and OFFFFFFFFH for PL/M-386) if the string 
contains only BYTE values equal to the target BYTE, or the index of the last BYTE 
value, if the last BYTE value in the string is not equal to the target BYTE. 

SKIPRW performs the same function as SKIPRB, except that SKIPRW searches for 
the last element in the WORD source string that does not match the WORD value of 
the target. 

For PL/M-386, SKIPHW performs the same function as SKIPB, except that 
SKIPHW searches an HWORD source string to find the first element that does not 
match the HWORD value of target. SKIPRHW also performs the same function as 
SKIPRB, except that SKIPRHW searches for the last element in the HWORD source 
string that does not match the HWORD value of the target. 
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9.4.6 The Translate String Procedure 



XLAT is an untyped procedure that uses a translation table to translate a BYTE string 
to produce another BYTE string. It is activated by a CALL statement of the form: 

CALL XLAT (source, destination, count, table) 



Where: 



PL/M-86 



source, expressions with 
destination, POINTER values 
and table 



count 



expression with 
WORD value 



PL/M-286 

expressions with 
POINTER values 



expression with 
WORD value 



PL/M-386 

expressions with 
POINTER values 



expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



XLAT translates the count BYTE elements in the source string, placing the translated 
elements in the destination string. The value of table is assumed to be the location of 
a BYTE string of up to 256 elements. This string is used as a translation table. 

The value of an element in the source string is used as an index into the translation 
table. The index selects one element from the translation table; this element is then 
copied into the destination string. 

For example, if the fifth element in the source string is 202, then 202 is used as an 
index for the translation table. The 203rd element of the table is copied into the fifth 
position in the destination string. 



The elements of the source string are translated into the destination string in ascend- 
ing order. 



9.4.7 The Set String to Value Procedure 

The SET built-in is an untyped procedure that sets each element of a BYTE string, 
the length of which is specified by count, to a single specified value. SET is activated 
by a CALL statement with the following form: 

CALL keyword (newvalue, destination, count) 
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Where: 



PL/M-86 



PL/M-286 



PL/M-386 



keyword SETB, SETW 



newvalue 



destination 



count 



expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
a BYTE or WORD 
value 



expression with 
POINTER value 

expression with 
BYTE or WORD 
value 



SETB, SETW 

expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
a BYTE or WORD 
value 



expression with 
POINTER value 

expression with 
BYTE or WORD 
value 



SETB, SETHW, 
SETW 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value — the high- 
order bits are 
dropped to produce 
a BYTE, WORD, or 
HWORD value 

expression with 
POINTER value 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



SETB assigns the BYTE value of newvalue to each element of a BYTE string. 

SETW performs the same function as SETB except that SETW assigns a single 
WORD value to each element of a WORD string. For PL/M-86 and PL/M-286, if 
newvalue has a BYTE value, it will be extended by 8 high-order zero bits to produce 
a WORD value. For PL/M-386, if newvalue has a BYTE or an HWORD value, it will 
be extended by 24 or 8 high-order bits, respectively, to produce a WORD value. 

For information on WORD32/WORD16 mapping, see Tables 9-3, 10-1 , and 11-3. 



Built-in Procedures, Functions, and Variables 



9-35 



PL/M-386 — 

| 9.5 PL/M-386 Bit Manipulation Built-lns 

9.5.1 The Copy BIT String Procedure 

MOVBIT is an untyped built-in procedure that copies a bit string of length count from 
one location to another. In memory, bits are numbered starting from the right. The 
right-most bit is the most significant bit. The left-most bit is the least significant bit. 
MOVBIT is activated by a CALL statement with the following form: 

CALL MOVBIT (sbase, sbitoffset, dbase, dbitoffset, count); 
Where: 

sbase and dbase are expressions with POINTER values. 

sbitoffset, are expressions with BYTE, HWORD, OFFSET, or WORD 

dbitoffset values, 
and count 

The MOVBIT built-in procedure moves the number of bits specified by count from 
the bit location given by the base address sbase, and the bit offset sbitoffset from that 
base to the location given by the base address dbase and the bit offset dbitoffset. 
These bits are moved beginning with the low-order bit (least significant bit). 

The M OVRBIT built-in procedure performs the same function as the MOVBIT built- 
in, except that MOVRBIT moves bits, in descending order, beginning with the high- 
order bit (most significant bit). 

9.5.2 The Find Set BIT Function 

SCANBIT is a built-in WORD function that searches a bit string to find a set bit, 
(i.e., a bit with the value of 1). In memory, bits are numbered starting from the right. 
The right-most bit is the most significant bit. The left-most bit is the least significant 
bit. SCANBIT is activated by a function reference with the following form: 

SCANBIT (sbase, sbitoffset, count) 
Where: 

sbase is an expression with a POINTER value. 

sbitoffset, are expressions with BYTE, HWORD, OFFSET, or WORD values. 
count 
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(continued) 

The SCANBIT built-in function searches the bit string of length count at the bit I 
location given by the base address sbase and the bit offset sbitoffset from that base for 
the first set bit, beginning with the low-order bit (least significant bit) in the string. 
The result of SCANBIT is either a WORD value of OFFFFFFFFH if the string con- 
tains all bits, or the index of the first set bit. 

SCANRBIT performs the same function as SCANBIT, except that SCANRBIT starts 
at the high-order bit (most significant bit) in the string and searches for a set bit, in 
descending order, and returns the location of the first set bit it encounters. The result 
of SCANRBIT is either a WORD value of OFFFFFFFFH if the string contains all 0- 
bits, or the index of the first set bit encountered. 

end 

PL/M-386 



9.6 Miscellaneous Built-lns 
9.6.1 The Move BYTES Procedure 

MOVE is an untyped procedure that moves the number of bytes specified by count to 
the location given by the value of destination, starting at the location given by the 
value of source. If the source and destination fields overlap, the result is undefined. 
MOVE is provided for compatibility with PL/M-80 programs. MOVE is activated by 
a CALL statement with the following form: 

CALL MOVE (count, source, destination) 
Where: 

PL/M-86 

count expression with 

WORD or BYTE 
value 

source and expressions with 
destination WORD values 



PL/M-286 

expression with 
WORD or BYTE 
value 

expressions with 
WORD values 



PL/M-386 

expression with 
BYTE, HWORD 
OFFSET, or WORD 
value 

expressions with 
OFFSET values 
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If either source or destination is a value other than the value specified in the preced- 
ing syntax description, the value will be extended by high-order bits to produce the 
appropriate value. The values of source and destination are assumed to be the 
addresses of the source string and the destination string. 

The operation of the MOVE procedure differs from the MOVB procedure (see Sec- 
tion 9.4.1), as follows: 

• The source and destination parameters must have the specified value. If they are 
other unsigned values, they will be converted to the correct value. POINTER 
values cannot be used, nor can values be supplied with the @ operator. Thus, 
MOVE can only handle strings whose locations can be expressed as the specified 
source and destination value addresses. 

• The parameters are in a different order than the one used by the other built-in 
string functions. 

• The results are always undefined if the source and destination strings overlap. 

9.6.2 The Time Delay Procedure 

TIME is an untyped built-in procedure that causes a time delay specified by its actual 
parameter. TIME is activated by a CALL statement with the following form: 

CALL TIME (expression); 

where the expression is converted, if necessary, to a WORD quantity for PL/M-86 
and PL/M-286 and to an HWORD quantity for PL/M-386. The length of time mea- 
sured by the procedure is a multiple of 100 microseconds. If the actual parameter 
evaluates to n, then the delay caused by the procedure is 100« microseconds. For 
example, the statement: 
CALL TINE (45) i 

causes a delay of 4.5 milliseconds. For PL/M-86 and PL/M-286, the maximum delay 
is 6.55 seconds. For PL/M-386, the maximum delay is 12 hours. If required, longer 
delays can be obtained by repeated activations. The following block takes one second 
to execute: 

DO I = 1 TO HO'-, 

CALL TIME (BSD) i 

END i 

The TIME procedure is based on the microprocessor's CPU cycle times. The TIME 
procedure assumes 8 MHz for the 8086 and the 80286 microprocessors and 16 MHz 
for the 80386 microprocessor. 
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9.6.3 The Memory Reference Array ^ 

MEiMORY is a BYTE array of unspecified length which represents an uninitialized 
(free) segment of the 8086 microprocessor's storage. References to MEMORY can 
be subscripted. The maximum subscript depends on both the system environment and 
the program. References to MEMORY, either subscripted or unqualified, can be used 
in location references. For example, @ MEMORY is the location of the beginning of 
free memory space (i.e., byte of the memory segment). 

A reference to MEMORY cannot be used as an actual parameter for the LENGTH, 
LAST, and SIZE procedures (see Sections 9.1.1 through 9.1.3). However, some 
systems provide service routines to determine the size of free memory. 

end 

PL/M-86 



9.6.4 The Lock Set Function 



LOCKSET is a built-in BYTE function that enables implementation of a simple soft- 
ware synchronization lock. It is called by a function reference with the following 
form: 



LOCKSET (lockptr, newvalue) 



Where: 



lockptr 



newvalue 



PL/M-86 

expression with 
POINTER value 

expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
a BYTE value 



PL/M-286 

expression with 
POINTER value 

expression with 
BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
a BYTE value 



PL/M-386 

expression with 
POINTER value 

expression with 
BYTE, HWORD, or 
WORD value — the 
high-order bits are 
dropped to produce 
a BYTE value 



The action of LOCKSET is as follows: the lockptr parameter is used as a pointer to a 
BYTE variable; the value of newvalue is assigned to this variable, and LOCKSET 
returns the original value of the variable. During this transaction, the microproces- 
sor's CPU prevents any other process from accessing the same memory location. 
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To see how this facility can be used, assume a system has more than one microproces- 
sor using the same memory, and has a program in one of these microprocessors. This 
program uses memory locations that are also used by other microprocessors in the 
system. 

Within certain critical regions of the program, it is critical that no other microproces- 
sor can access the shared memory locations. To achieve this, declare a global BYTE 
variable called LOCK, and establish a convention that if LOCK = 0, any micropro- 
cessor in the system can access the shared memory locations. However, if LOCK = 1 , 
no microprocessor can access the shared memory locations except for the micropro- 
cessor that set LOCK to 1 . 

Write the function reference LOCKSET(@LOCK, 1). The value 1 will be assigned to 
LOCK. If the value returned by LOCKSET is 0, then LOCK has not been set, and 
this microprocessor is the one that set it. At the end of the critical region, the lock 
must be released by writing LOCK = 0. 

If LOCKSET returns a value of 1 , then LOCK has been set and this microprocessor 
was not the one that set LOCK. Wait until a LOCKSET(@LOCK,l) function refer- 
ence returns a value of before accessing the shared memory locations. 

Thus, the program could contain the following construction: 

/*Begin critical region*/ 

DO WHILE LOCKSETOLOCK-,1) ; 

/*Do nothing but repeat until LOCKSET returns 0*/ 

END i 

/*Now LOCK has been set to 1 by this microprocessor*/ 

• ■ ■ 

/♦Critical region of programi where shared 
memory locations are accessed*/ 

L0CK = D=, 

/*End critical region*/ 

In the simple case just described, only one software lock is used. It is represented by 
the variable LOCK. But, if more than one set of memory locations needed protection 
at different times, it is possible to establish as many different software locks as neces- 
sary, with each lock using a different BYTE variable. 

Also, note that a software lock can be used for purposes other than protecting mem- 
ory locations. LOCKSET provides a mechanism that can be used to implement vari- 
ous types of synchronization in a multiprocessor system. 
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9.6.5 The Lock BIT Function 

Lock BIT is a built-in BYTE function that is similar to the LOCKSET built-in de- 
scribed in the previous section. It is a BYTE procedure called by a function reference 
with the form: 

keyword (bbase, boffset) 
Where: 

keyword is BITLOCKSET, BITLOCKRESET, or BITLOCKCOMPLEMENT. 

bbase is an expression with a POINTER value. 

boffset is an expression with a BYTE, HWORD, or WORD value. 

The action of BITLOCKSET is as follows: the bbase and boffset parameters are used 
as the base address and bit offset to point to a certain bit in memory. The value 1 is 
assigned to this variable, and BITLOCKSET returns a BYTE. The returned value is 
TRUE (OFFH) if the original content of the bit was 1, otherwise it is FALSE. During 
this transaction, the microprocessor's CPU prevents any other process from access- 
ing the same memory location. BITLOCKRESET performs the same function as 
BITLOCKSET, except that BITLOCKRESET assigns the value to the bit variable. 
BITLOCKCOMPLEMENT performs the same function as BITLOCKSET, except 
that BITLOCKCOMPLEMENT complements the BYTE variable; that is, if the value 
was initially 0, it is set to 1 and vice versa. 

end 

PL/M-386 

PL/M-86 

9.7 Interrupt-Related Procedures 

The two capabilities described in this section enable PL/M-86 programs to set inter- 
rupt vectors and determine the entry point of an interrupt-handling procedure. For 
detailed information concerning interrupt handling procedures, see the 8086 refer- 
ence literature. 
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9.7.1 The Set Interrupt Vector Procedure 

The SET$INTERRUPT procedure enables an executing program to set an interrupt 
vector to point to the interrupt entry point of a separately compiled interrupt handling 
routine, or to alter such vectors dynamically. See also Section 8.5.1 and Appendix G. 

The procedure is invoked by a CALL of the following form: 
CALL SET$INTERRUPT (constant,name) 

where name is the interrupt procedure name, and constant is an interrupt number 
(i.e., a whole-number constant between and 255). Name must be a previously 
declared interrupt procedure. 

PL/M-86 — 

(continued) 

9.7.2 The Return Interrupt Entry Point Function 

The INTERRUPT$PTR built-in function returns the interrupt entry point. 
INTERRUPT$PTR has the following form: 

INTERRUPT$PTR (name) 

INTERRUPT$PTR is typically used in an assignment statement, for example: 
INT$ARRAY<4) = INTERRUPTSPTR ( H ANDLER_PR0C_4 ) 

The interrupt entry point is not accessible without using this function, since the @ 
operator refers to the procedure entry point instead. These differences are discussed 
in greater detail in Appendix G. Name must be a previously declared interrupt 
procedure. 

86 — 

9.8 POINTER and SELECTOR-Related Functions 

With the following built-in functions, programs can manipulate POINTER and 
SELECTOR values that serve as location addresses in the microprocessor's memory. 

9.8.1 The Return POINTER Value Function 

BUILD$PTR is a built-in POINTER function that takes the specified segment and 
offset value and returns a POINTER value. It is activated by a function reference with 
the following form: 

BUILD$PTR (segment, offset) 
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Where: 



PL/M-86 



PL/M-286 



PL/M-386 



segment 



expression with 
SELECTOR value 



expression with 



expression with 



SELECTOR value 



SELECTOR value 



offset 



expression with 
WORD value 



expression with 
WORD value 



expression with 



OFFSET value 



9.8.2 The Return Segment Portion of POINTER Function 

SELECTOR$OF is a built-in SELECTOR function that returns the segment portion 
of a POINTER. It is activated by a function reference with the following form: 

SELECTOR$OF (pointer) 
Where: 



9.8.3 The Return Offset Portion of POINTER Function 

OFFSET$OF returns the offset portion of a POINTER. For PL/M-86 and PL/M- 
286, OFFSET$OF is a built-in WORD function. For PL/M-386, OFFSET$OF is a 
built-in OFFSET function. It is activated by a function reference with the following 
form: 

OFFSET$OF (pointer) 
Where: 



pointer is an expression with a POINTER value. 



pointer is an expression with a POINTER value. 
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9.8.4 The Set POINTER Bytes to Zero Variable 



NIL is a built-in POINTER pseudo-variable that represents a pointer with all bytes set 
to zero. NIL is activated by a function reference with the following form: 

NIL 

The pointer value NIL points to no object. The value NIL can be assigned to a pointer 
to indicate, for instance, the end of a linked list. 

Note that pointer values equal to NIL cannot be used to de-reference data values. For 
example, if a program contains the following statements: 

DECLARE P POINTERS 
DECLARE B BASED P BYTE i 
P = NIL i 

any subsequent references to B are invalid and will cause a trap. 

The NIL POINTER variable also has the property that @NIL is equal to NIL. 

POINTER variables can be initialized to NIL by using @NIL with INITIAL. For 
example: 

DECLARE ENDOFLIST POINTER 
INITIAL ( 9 N I L ) i 

initializes ENDOFLIST with the value of NIL (i.e., all zeros). OFFSET$OF(NIL) 
and .NIL are also equal to zero. 
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NOTE I 

Using the NIL pointer can lead to undesirable results. 

In the SMALL case, a NIL pointer is defined to be DS:0, which is not distin- 
guishable from a valid pointer to the first variable in the data segment (DS). For 
example: 

SSrIALL 

rt:]>o; 

DECLARE P POINTER INITIAL OP); 
DECLARE B BYTE; 

B = (P=NIL); /* will assign TRUE (DFFH) to B */ 

end; 

In all other cases, the NIL pointer is defined to be 0:0, which is not distinguish- 
able from a valid pointer to a variable located at absolute address 0. For 
example: 

$L ARGE 
M : do; 

DECLARE a BYTE AT <□) ; 

DECLARE B BYTE; | 
B + Oi2=NIL); /* will assign TRUE (DFFH) to B */ 
END; I 

end 

— PL/M-86 



— PL/M-386 

I 

9.9 WORD16 Built-in Mapping for the 80386 
Microprocessor 

The native machine word for the 80386 microprocessor is WORD32 (a 32-bit 
WORD). The WORD 16 control effects the semantics of some data types and built-ins 
as listed in Table 9-3. In PL/M-386, WORD16 keywords are mapped to the equiva- 
lent WORD32 keyword. SELECTOR, POINTER, OFFSET, (ADDRESS) are the 
same under both WORD32 and WORD16. WORD32 terminology is also repeated in 
the following table. 
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(continued) Table 9-3 WORD32/WORD16 Mapping for Built-ins 





WORD32 


WORD 1 o 




BYTE 


BYTE, HWORD 




HWORD 


WORD 


Type conversion 


i a //-\ n r\ 

WORD 


DWORD 


built-ins 


DWORD, QWORD 


QWORD 


(casts) 


CHARINT 


PUADTIMT I l a niMT 

SHORTINT, CHARINT 




SHORTINT 


INTECaER 




INTEGER 


LONGINT 




MOVB 


MOVB 




MOVRB 


MOVRB 




FINDB 


FINDB 


8-bit built-ins 


FINDRB 


FINDRB 




SKIPB 


SKIPB 




SKIPRB 


SKIPRB 




CMPB 


CMPB 




SETB 


SETB 




MOVHW 


MOVW 




MOVRHW 


MOVRW 




FINDHW 


FINDW 


16-bit built-ins 


FINDRHW 


r— 1 h 1 r\n\ A ( 

FINDRW 




n L/i ni ma/ 

SKIPHW 


o \y i n\ a i 

SKIPW 




SKIPRHW 


SKIPRW 




CMPHW 


CMPW 




SETHW 


SETW 




MOVW 


MOVD 




MOVRW 


MOVRD 




FINDW 


FINDD 


32-bit built-ins 


FINDRW 


FINDRD 




SKIPW 


SKIPD 




SKIPRW 


SKIPRD 




CMPW 


CMPD 




SETW 


SETD 



end 

PL/M-386 
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FEATURES INVOLVING 
THE TARGET CPU AND 
NUMERIC COPROCESSOR 



The PL/M features described in this chapter make direct or indirect use of the target 
microprocessor and numeric coprocessor hardware. 



10.1 Microprocessor Hardware-Dependent Statements 
10.1.1 The ENABLE and DISABLE Statements 



These statements enable and disable the microprocessor interrupt mechanism. 

The ENABLE statement has the following form: 
ENABLE; 

ENABLE generates an STI instruction, causing the microprocessor to enable 
interrupts after the next machine instruction is executed. 

The DISABLE statement has the following form: 
DISABLE; 

DISABLE generates a CLI instruction, causing the microprocessor to disable 



The CAUSE$INTERRUPT statement causes a software interrupt to be generated. It 
takes the form: 

CAUSE$INTERRUPT (constant); 
Where: 

constant is a whole-number constant in the range to 255. 

CAUSE$INTERRUPT generates an INT instruction with the constant as the interrupt 
type, causing the microprocessor to transfer control to the appropriate interrupt vec- 
tor. Appendix G contains more information on run-time interrupt processing. 



interrupts. 



10.1 .2 The CAUSE$INTERRUPT Statement 
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10.1.3 The HALT Statement 



The HALT statement cause a microprocessor halt with interrupts enabled. The HALT 
statement has the form: 

HALT; 

It generates an STI instruction followed by an HLT instruction, causing the micropro- 
cessor to halt with interrupts enabled. 

10.2 Microprocessor Hardware Flags 
10.2.1 Optimization and the Hardware Flags 

To produce an efficient machine-code program from a PL/M source program, PL/M 
compilers perform extensive optimizations of the machine code. This means that the 
exact sequence of machine code produced to implement a given sequence of PL/M 
source statements cannot be predicted. 

Consequently, the state of the microprocessor hardware flags cannot be predicted for 
any given point in the program. For example, suppose that a source program contains 
the following fragment: 

sun = sun + %M\ 

Where: 

SUn is a BYTE variable. 

Now, if the value of SUM before this assignment statement is greater than five, the 
addition will cause an overflow and the hardware CARRY flag will be set. 

If there were no optimization of the machine code, this assignment statement could be 
followed with one of the PL/M features described in the following sections. This 
would ensure that the feature would operate in a certain fashion depending on 
whether or not the addition caused the CARRY flag to be set. However, because of 
the optimization, some machine code instructions could occur immediately after the 
addition and change the CARRY flag. It cannot be safely predicted whether this will 
happen or not. 
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NOTE 



Accordingly, any PL/M feature that is dependent on the CARRY flag (or any of 
the other hardware flags) can cause the program to run incorrectly. These fea- 
tures must therefore be used with caution, and any program that uses them 
must be checked carefully to make sure that it operates correctly. 



10.2.2 The CARRY, SIGN, ZERO, and PARITY Functions 

These built-in BYTE functions return the logical values of the microprocessor hard- 
ware flags. These functions take no parameters, and are activated by function refer- 
ences with the following forms: 

CARRY 
ZERO 
SIGN 
PARITY 

An occurrence of one of these activations (in an expression) generates a test of the 
corresponding condition flag. If the flag is set ( = 1), a value of OFFH is returned. If 
the flag is clear ( = 0), a value of is returned. 



10.2.3 The PLUS and MINUS Operators 

In addition to the arithmetic operators described in Section 5.6, PL/M has two more: 
PLUS and MINUS. 

PLUS and MINUS perform similarly to + and — , and have the same precedence. 
However, PLUS sums two numbers and adds the CARRY bit to the result and 
MINUS subtracts two numbers and subtracts the CARRY bit from the result. 



10.2.4 Carry-Rotation Functions 

SCL and SCR are built-in rotation functions whose types depend on the type of the 
expression given as an actual parameter. They are activated by function references 
with the following forms: 

keyword (pattern, count); 
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Where: 



PL/M-86 



PL/M-286 



PL/M-386 



keyword 



SCL, SCR 



SCL, SCR 



SCL, SCR 



pattern 
and count 



BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
BYTE values 



expressions with 



BYTE or WORD 
value — the high- 
order bits are 
dropped to produce 
BYTE values 



expressions with 



expressions with 
BYTE, HWORD, 



WORD, OFFSET, or 



DWORD value — 
the high-order bits 
are dropped to pro- 
duce BYTE values 



If the value of count is 0, no shift occurs. 

For PL/M-86 and PL/M-286, the value of pattern is handled as an 8-bit or 16-bit 
binary quantity. For PL/M-386, the value of pattern is handled as an 8-bit, 16-bit, 32- 
bit, or 64-bit binary quantity. This quantity is rotated to the left (by SCL) or to the 
right (by SCR). This is similar to the ROL and ROR functions described in Chapter 9. 
The type of pattern determines the type of rotate that is performed. The number of bit 
positions by which the value of pattern is rotated is specified by count. 

The bit rotated off one end of pattern is rotated into the CARRY flag, and the old 
value of CARRY is rotated to the other end of pattern. In effect, SCL and SCR 
perform 9-bit rotations on 8-bit values and 17-bit rotations on 16-bit values, and 
so on. 

For example, if the value of CARRY is 0, then: 

SCLCLIDDIOIOB-, E) returns a value of 00101001B and CARRY is set to 1 

SCRCUDDlDlDB-i 1) returns a value of 01 100 10 IB and CARRY remains 

10.2.5 The Decimal Adjust Function 

DEC is a built-in BYTE function that performs a decimal adjust operation on the 
actual parameter value and returns the result of this operation. For PL/M-86 and 
PL/M-286, DEC uses the value of the hardware CARRY flag internally. For PL/M- 
386, DEC uses the value of the hardware AUXILIARY CARRY flag internally. It is 
activated by a function reference with the following form: 



DEC (expression); 



Where: 



expression is converted, if necessary, to a BYTE value. 
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10.3 Microprocessor Hardware Registers 



1 0.3.1 The Flags Register Access Variable 

FLAGS is a built-in WORD variable that provides access to the microprocessor's 
hardware flags register (see Figure 10-1). The hardware flags register contains the 
hardware flags that are altered by the execution of various instructions. The hardware 
flags register for the 8086 and the 80286 microprocessors is 16-bit. The hardware 
flags register for the 80386 microprocessor is 32-bit. 

The FLAGS register is assigned to change the setting of the various flags. It can also 
be read to determine the current flag settings. 

For more information on setting the hardware register flags, see the appropriate pro- 
grammer's reference manual. 
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•H 


80286 



XX ■ ■■ X I VIUl| RF| X I NT I IOPL | OF | DF | IF | TF | SF | ZF | X | Af| X | PF | X [cf| 80386 

I- CARRY FLAG 

PARITY FLAG 

AUXILIARY CARRY FLAG 

ZERO FLAG 

SIGN FLAG 

SINGLE-STEP TRAP FLAG 

INTERRUPT ENABLE 

DIRECTION 

OVERFLOW 

IOPL 

NESTED TASK 

RESUME FLAG 

VIRTUAL 8086 MODE 

X DENOTES INTEL RESERVED. 



m-0885 

Figure 10-1 The Hardware Flags Register 
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10.3.2 The STACKPTR and STACKBASE Variables 



For PL/M-86 and PL/M-286, STACKPTR and STACKBASE are WORD variables. 
For PL/M-386. STACKPTR is an OFFSET variable and STACKBASE is a SELEC- 
TOR variable. They provide access to the microprocessor's hardware stack pointer 
and stack base registers. 

When setting these registers (that is, using STACKPTR or STACKBASE on the left 
side of an assignment), care must be exercised because this takes control of the stack 
away from the compiler. Thus, the compile-time checks on stack overflow and as- 
sumptions by the compiler about the run-time status of the stack may be invalid. 

10.4 Microprocessor Hardware I/O 
86/286 — 

Single BYTE or WORD input is performed by the input built-ins as a function invo- 
cation in an expression on the right-hand side of an assignment statement. Single 
BYTE or WORD output is achieved by filling the appropriate element of the output 
array corresponding to the desired output port of the target microprocessor. 

Multiple BYTE or WORD input is performed as a procedure invocation, reading in a 
string from the microprocessor's CPU port and storing it in a user-specified memory 
location. Multiple BYTE or WORD output is also performed as a procedure invoca- 
tion, using a CALL statement to send a string from memory into the target micropro- 
cessor. 

86/286 — 
PL/M-386 — 

Single BYTE, HWORD, OFFSET, or WORD input is performed by the input built- 
ins as a function invocation in an expression on the right-hand side of an assignment 
statement. Single BYTE, HWORD, OFFSET, or WORD output is achieved by filling 
the appropriate element of the output array corresponding to the desired output port 
of the target microprocessor. 
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PL/M-386 

(continued) 



Multiple BYTE, HWORD, OFFSET, or WORD input is performed as a procedure 
invocation, reading in a string from the microprocessor's CPU port and storing it in a 
user-specified memory location. Multiple BYTE, HWORD, OFFSET, or WORD 
output is also performed as a procedure invocation, using a CALL statement to send a 
string from memory into the target microprocessor port. 



I 
I 

end 



10.4.1 The Find Value in Input Port Function 

The following built-in functions return the values in the specified input port. They are 
activated by function references with the form: 

keyword (expression); 
Where: 

PL/M-86 PL/M-286 PL/M-386* 

keyword INPUT, INWORD INPUT, INWORD INPUT, INHWORD, 

INWORD 

expression expression with expression with expression with BYTE, 
BYTE or WORD BYTE or WORD HWORD or WORD 
value value value 

*Seealso Section 10.4.3. 

The value of expression specifies one of the input ports of the target microprocessor. 

The value returned by the keyword is the expression quantity found in the specified 
input port. 

PL/M-386 also has an INDWORD function when the WORD 16 control is used. 

10.4.2 The Access Output Port Array 

For PL/M-86 and PL/M-286, OUTPUT and OUTWORD are built-in BYTE and 
WORD arrays, respectively. For PL/M-386, OUTPUT, OUTHWORD, and 
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OUT WORD are built-in BYTE, HWORD, and WORD arrays, respectively. They are 
activated by a function reference with the following form: 



keyword (expression); 



Where: 



PL/M-86 



PL/M-286 



PL/M-386* 



keyword 



OUTPUT, 
OUTWORD 



OUTPUT, 
OUTWORD 



OUTPUT, 

OUTHWORD, 

OUTWORD 



expression 



BYTE or WORD 
value 



expression with 



expression with 
BYTE or WORD 
value 



expression with 
BYTE, HWORD, or 
WORD value 



*See also Section 10.4.4. 

These functions can access any port from to 65,556, corresponding to the number 
of output ports on the target CPU. References to these arrays cause the specified 
expression quantity to be latched to the specified hardware output port. 

A reference to keyword is legal only as the left part of an assignment statement or 
embedded assignment. For PL/M-86 and PL/M-286, the right-hand side of the as- 
signment must have a BYTE or WORD value. For PL/M-386, the right-hand side of 
the assignment must have a BYTE, HWORD, or WORD value. 

Assignment to an element of OUTPUT places the BYTE value of the expression on 
the right side of the assignment into the corresponding output port. (Since OUTPUT 
is a BYTE built-in, the value of the expression is converted automatically to a type 
BYTE if necessary.) 

Assignment to an element of OUTWORD places the WORD (additionally, for PL/M- 
386, OFFSET) value of the expression on the right side of the assignment into the 
corresponding output port. 

For PL/M-386, assignment to an element of OUTHWORD places the HWORD value 
of the expression on the right side of the assignment into the corresponding output 
port. 



PL/M-386 also has an OUTDWORD built-in when the WORD16 control is used (see 
Section 10.8). 
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10.4.3 The Read and Store String Procedure 



The read and store string procedures are built-in. For PL/M-86 and PL/M-286, these 
built-ins read the BYTE or WORD string values latched to the specified hardware 
input port. For PL/M-386, these built-ins read the BYTE, HWORD, OFFSET, or 
WORD string values latched to the specified hardware input port. The read values, of 
the length specified by count, are then stored at the location specified by destination. 
These procedures are activated by a CALL statement with the following form: 

CALL keyword (port, destination, count); 



Where: 



PL/M-86* 



PL/M-286 



keyword 



port 



BLOCKINPUT, BLOCKINPUT, 

BLOCKINWORD BLOCKINWORD 

expression with expression with 

BYTE or WORD BYTE or WORD 

value value 

destination expression with expression with 

POINTER value POINTER value 



count 



expression with expression with 
BYTE or WORD BYTE or WORD 
value value 



PL/M-386** 

BLOCKINPUT, 

BLOCKINHWORD, 

BLOCKINWORD 

expression with 
BYTE or HWORD 
value 

expression with 
POINTER value 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 



*To use this procedure in PL/M-86, the MOD 186 control must be used (see Section 11.1.1). 
"See Section 10.4.1. 



The keyword specifies the type of string found in the specified input port. The value 
of port specifies one of the input ports of the CPU. The destination specifies the 
location (in memory) at which to store the string. The value of count specifies the 
length of the string. 



PL/M-386 also has a BLOCKINDWORD procedure when the WORD 16 control is 
used (see Section 10.8). 
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10.4.4 The Write String Procedure 



The write string procedures are built-in procedures. For PL/M-86 and PL/M-286, 
these built-ins write a BYTE or WORD string to the specified hardware output port. 
For PL/M-386, these built-ins write a BYTE, HWORD, OFFSET, or WORD string 
to the specified output hardware port. These built-ins are activated by a CALL state- 
ment with the following form: 

CALL keyword (port, source, count); 
Where: 

PL/M-86* PL/M-286 PL/M-386** 

BLOCKOUTPUT, 
BLOCKOUTHWORD, 
BLOCKOUTWORD 

expression with 
BYTE or HWORD 
value 

expression with 
POINTER value 

expression with 
BYTE, HWORD, 
OFFSET, or WORD 
value 

*To use this procedure in PL/M-86, the MOD 1 86 control must be used (see Section 11.1.1). 
**See Section 10.4.2. 

The keyword specifies the type of string. The value of port specifies one of the output 
ports of the microprocessor CPU. The source value specifies the location (in mem- 
ory) where the string is currently stored. The value of count specifies the string 
length. 

PL/M-386 also has a BLOCKOUTDWORD procedure when the WORD 16 control is 
used (see Section 10.8). 



keyword BLOCKOUTPUT, BLOCKOUTPUT, 
BLOCKOUTWORD BLOCKOUTWORD 



port expression with 

BYTE or WORD 
value 

source expression with 
POINTER value 

count expression with 
BYTE or WORD 
value 



expression with 
BYTE or WORD 
value 

expression with 
POINTER value 

expression with 
BYTE or WORD 
value 
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— PL/M-286/386 

10.5 The Hardware Protection Model ^ 

The 80286 and the 80386 microprocessors' protection mechanism provides up to four 
privilege levels within each task. The highest privilege level (level 0) is reserved for 
the operating system kernel. Below the kernel level, systems can be configured to 
include a system service level (level 1), an applications service level (level 2), and an 
application program level (level 3). 



The following hardware protection built-in procedures and variables allow access to 
the protection architecture of the 80286 and the 80386 microprocessors. 



10.5.1 The Task Register 

10.5.1.1 The TASK$REGISTER Variable 

TASK$REGISTER is a built-in SELECTOR variable that provides access to the task 
state register. This register points to a task state segment for the currently executing 
task. The format of the task register is: 



INDEX 



Tl 



RPL 



31 
15 



PL/M-286 
PL/M-386 



19 

3 



18 17 
2 1 



16 




Values are assigned to TASK$REGISTER to reset the task state segment for the 
current task or to enter the protected mode of the microprocessor. However, the 
selector stored in TASK$REGISTER must point to a valid task state segment. Note 
that values can only be assigned to TASK$REGISTER if the program is executed in 
protection mode at level 0. 



TASK$REGISTER can also be read to determine the task state segment of the cur- 
rently executing task. 



10.5.2 The Global Descriptor Table Register 

The global descriptor table register (GDTR) is a system-wide register used for pro- 
tected virtual address mode. The GDTR describes a memory area that contains an 
array of descriptors for the global address space. The register occupies 6 bytes. 
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PL/M-286/386 — 

(continued) 

Its format for the 80286 microprocessor is as follows: 





LIMIT 


BASE 


ACCESS 


47 32 


31 




8 


7 


Its format for the 80386 microprocessor is as follows: 








BASE 


LIMIT 


47 


16 


15 








LIMIT — size of the GDT segment (up to 64K bytes) 
BASE — physical memory base address of the GDT segment 
ACCESS — access control byte 

10.5.2.1 The SAVE$GLOBAL$TABLE Procedure 

SAVE$GLOBAL$TABLE is a built-in procedure. It is activated by a CALL statement 
with the form: 

CALL SAVE$GLOBAL$TABLE (location); 
Where: 

location is an expression with a POINTER value. 

SAVE$GLOBAL$TABLE saves the contents of the hardware global descriptor table 
register in the 6-byte save area pointed to by location. 

Specific to the 80286 microprocessor, the memory value of the access byte is unde- 
fined after a call to SAVE$GLOBAL$TABLE. 

10.5.2.2 The RESTORE$GLOBAL$TABLE Procedure 

RESTORE$GLOBAL$TABLE is a built-in procedure. It is activated by a CALL 
statement with the form: 

CALL RESTORE$GLOBAL$TABLE (location); 
Where: 

location is an expression with a POINTER value. 
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— PL/M-286/386 

(continued) 

RESTORE$GLOBAL$TABLE restores the contents of the hardware global descrip- 
tor table register from the save area pointed to by location. This save area can be the 
same area used in a preceding call to SAVE$GLOBAL$STATUS. 

SAVE$GLOBAL$TABLE saves the value of the GDTR in a 6-byte memory area. 
RESTORE$GLOBAL$TABLE restores the value of the GDTR. 

10.5.3 The Interrupt Descriptor Table Register 

The interrupt descriptor table register (IDTR) is a system-wide register that is used 
for interrupt processor management. The IDTR describes a segment that contains the 
linear base address and the size of the interrupt descriptor table (IDT), and a segment 
containing an array of gate descriptors for the interrupt handlers. The register occu- 
pies 6 bytes. 



For the 80286 microprocessor, it has the following format: 





LIMIT 


BASE 


ACCESS 




47 32 


31 


8 


7 


For the 80386 microprocessor, it has the following format: 






BASE 


LIMIT 




47 


16 


15 






LIMIT — size of the segment (up to 64K bytes) 

BASE — physical memory base address of the IDT segment 
ACCESS — access control byte 



10.5.3.1 The SAVE$INTERRUPT$TABLE Procedure 

SAVE$INTERRUPT$TABLE is a built-in procedure that is activated by a CALL 
statement with the following form: 

CALL SAVE$INTERRUPT$TABLE (location); 
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is an expression with a POINTER value. 

SAVE$INTERRUPT$TABLE saves the contents of the hardware interrupt descriptor 
table register in the 6-byte save area pointed to by location. 

10.5.3.2 The RESTORE$INTERRUPT$TABLE Procedure 

RESTORE$INTERRUPT$TABLE is a built-in procedure that is activated by a CALL 
statement with the following form: 

CALL RESTORE$INTERRUPT$TABLE (location); 
Where: 

location is an expression with a POINTER value. 

RESTORE$INTERRUPT$TABLE restores the contents of the hardware interrupt de- 
scriptor table register from the save area pointed to by location. This save area can be 
the same area used in a preceding call to SAVE$INTERRUPT$TABLE. 

A descriptor can be built that will initialize the interrupt processor operations. 
RESTORE$GLOBAL$STATUS can then be called with a pointer to this descriptor. 

The user must ensure that the save area contains a valid descriptor. Note that values 
can only be assigned to the IDTR if the program is executed in protection mode at 
level 0. 

10.5.4 The Local Descriptor Table Register 

10.5.4.1 The LOCAL$TABLE Variable 

LOCAL$TABLE is a built-in SELECTOR variable that provides access to the local 
descriptor table register (LDTR). The format of the register is a selector pointing to 
an LDT in the GDT The use of the local descriptor table is like the use of the GDTR, 
except that it defines the local address space. 



PL/M-286/386 

(continued) 



location 
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(continued) 

By assigning a value to LOCAL$TABLE, the local address space of the current task 
is altered. If a task switch occurs, the new contents are not saved in the task state 
segment. (To ensure proper operation, interrupts must be disabled.) 

LOCAL$TABLE can be read to determine the current active descriptor array seg- 
ment for the current task. 

The user must ensure that the selector in LOCAL$TABLE points to a valid descriptor 
segment. Note that values can only be assigned to the LDTR when the program is 
executed in protection mode at level 0. 

10.5.5 The Machine Status Register 

10.5.5.1 The MACHINE$STATUS Variable 

For PL/M-286, MACHINE$STATUS is a built-in WORD variable. For PL/M-386, 
MACHINE$STATUS is a built-in HWORD variable. MACHINE$STATUS provides 
access to the machine status word (MSW). The MSW register defines the current 
status of the processor protection model and the real math unit support. The format of 
MACHINE$STATUS is: 



X 


X 


X 


TS 


EM 


MP 


PE 



15 14 4 3 2 1 



PROTECTION ENABLE 

REAL MATH UNIT (iAPX 287) PRESENT 

EMULATION MODE 

TASK SWITCHED 

(RESERVED) 

(RESERVED) 

(RESERVED) 

121945-3 
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PL/M-286/386 — 

(continued) 

IMACHINE$STATUS enables access to the protected mode of the microprocessor. 
When a value is assigned to this register, the compiler generates a short jump to the 
next instruction to clear the instruction queue. (Note, however, that values can only 
be assigned to MACHINE$STATUS if the program is executed in protection mode at 
level 0.) 



NOTE 

Once the protection mode has been accessed, the only way to return to real 
address mode is by executing a hardware RESET. 

I The contents of MACHINE$STATUS can also be read to determine the current status 
of various system components. 

end 

PL/M-286/386 — 
PL/M-386 — 

10.5.5.2 The CONTROL$REGISTER, DEBUG$REGISTER, and 
' TEST$REGISTER Built-in Arrays 

The CONTROL$REGISTER is a built-in WORD array that provides access to the 
80386 microprocessor's 32-bit control registers that define the current status of the 
processor and contain page table and page fault information. 

The format of CONTROL$REGISTER (0) is: 



PG 


X 


X 


ET 


TS 


EM 


MP 


PE 





X reserved 
PG paging enabled 
ET extension type 
TS task switched 
EM emulation mode 

MP real math unit (numeric coprocessor) present 
PE protection enable 

MSW is contained in the low-order 16 bits of CONTROL$REGISTER (0). However, 
assigning a value to the MACHINE$STATUS built-in does not change the ET (exten- 
sion type) bit. 
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(continued) 

CONTROL$REGISTER (2) contains the 32-bit linear address that caused the last 
detected page fault. 

CONTROL$REGISTER (3) contains the physical page base address for the first 
level of the page table structure. This address is in the high 20 bits (bits 12 to 31) of 
CONTROL$REGISTER (3). The lower 12 bits are ignored when assigning to CON- 
TROL$REGISTER (3) and are undefined when reading CONTROL$REGISTER 
(3). Note that the control registers are accessible only during execution at protected 
mode level 0. Also note that CONTROL$REGISTER (1) is not accessible. 

The DEBUG$REGISTER built-in WORD array provides access to six of the eight 
32-bit debug registers; DEBUG$REGISTER(4) and DEBUG$REGISTER(5) are not 
accessible. The debug registers are accessible only during execution at protected 
mode level 0. 

TEST$REGISTER is a built-in WORD array that provides access to the 32-bit test 
registers of the 80386 microprocessor. Of these test registers, only TEST 
$REGISTER (6) and TEST$REGISTER (7) are accessible; these registers are acces- 
sible only when executing in protection mode at level 0. 

end 

— PL/M-386 



— PL/M-286/386 

10.5.5.3 The CLEAR$TASK$SWITCHED$FLAG Procedure I 

CLEAR$TASK$SWITCHED$FLAG is a built-in procedure that is activated by a 
CALL statement with the form: 

CALL CLEAR$TASK$SWITCHED$FLAG; 

This procedure is used to clear the task switched flag in the machine status word. The 
processor sets the task switched flag every time a task switch occurs. It can be used to 
manage the sharing of the real math coprocessor. 

CLEAR$TASK$SWITCHED$FLAG can only be called when the program is exe- 
cuted in protection mode at level 0. 
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PL/M-286/386 — 

(continued) 

10.5.6 Segment Information 

10.5.6.1 The GET$ACCESS$RIGHTS Function 

GET$ACCESS$RIGHTS is a built-in WORD function; it is activated by a function 
reference with the form: 

GET$ACCESS$RIGHTS {selector); 
Where: 

selector is an expression with a SELECTOR value. 

If the segment pointed to by selector is visible at the current privilege level, then the 
hardware ZERO flag is set and a WORD value returned. If the segment is not visible, 
or if it is of the wrong type, the hardware ZERO flag is reset, and the value returned 
is undefined. 

NOTE 

The setting of the ZERO flag is guaranteed only if it is tested immediately, 
before being altered by another operation. (For example, if the value of the 
function is assigned to an array element indexed by an expression, the value of 
the ZERO flag may be incorrect.) 



Specific to the 80386 microprocessor, the format of the return value is: 









G 








AVL 


X 


X 


ACCESS 




















31 


24 


23 


22 


21 


20 


19 


16 


15 8 


7 






X reserved 

G granularity bit 

AVL available for software use 

ACCESS access rights byte 
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(continued) 

The following example illustrates how the GET$ACCESS$RIGHTS function can be 
used: I 

DECLARE RIGHTS WORD, 
DECLARE SEGMENT SELECTORS 

RIGHTS = GET5ACCESSSRIGHTS ( SEGMENT ) i 
IF ZERO THEN 

/* The segment pointed to by SEGMENT is visible */ 
/* and RIGHTS contains the proper access */ 

/* rights to it. */ 

ELSE 

/* SEGMENT is not visible and the contents of */ 

/* RIGHTS is undefined. */ 

10.5.6.2 The GET$SEGMENT$LIMIT Function 

For PL/M-286, GET$SEGMENT$LIMIT is a built-in WORD function. For 
PL/M-386, GET$SEGMENT$LIMIT is a built-in OFFSET function. GET- 
$SEGMENT$LIMIT is activated by a function call of the form: 

GET$SEGMENT$LIMIT (selector); 
Where: 

selector is an expression with a SELECTOR value. 

If the segment pointed to by selector is visible at the current protection level, then the 
hardware ZERO flag is set and the value returned by GET$SEGMENT$LIMIT is the 
size of the segment. Otherwise, if the segment is not visible, the ZERO flag is reset 
and the value returned is undefined. 

Set the ZERO flag with caution. See the note in Section 10.5.6. 1. 

The following example (for PL/M-286) illustrates how the 
GET$SEGMENT$LIMIT function can be used: 

DECLARE LIMITS UORD i 
DECLARE SEGMENT SELECTORS 

LIMITS = GET$SEGMENT$LIMIT ( SEGMENT ) i 
IF ZERO THEN 

/* The segment pointed to by SEGMENT is visible */ 
/* and LIMITS contains its proper size- */ 

ELSE 

/* SEGMENT is not visible and the contents of */ 

/* LIMITS is undefined. */ 
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PL/M-286/386 — 

(continued) 

10.5.7 Segment Accessibility 

It is sometimes helpful to know if the segment pointed to by a selector is readable or 
writable from the current address space. This becomes particularly important when 
the selector is a parameter that is passed to the current task. 

If an attempt is made to access a segment that is inaccessible, an interrupt will occur. 
To avoid this interrupt, segment readability and writability can be tested before the 
segment is accessed. 

10.5.7.1 The SEGMENT$READABLE Function 

SEGMENT$READABLE is a built-in BYTE function. It is activated by a function 
reference with the form: 

SEGMENT$READABLE (selector); 
Where: 

selector is an expression with a SELECTOR value. 

SEGMENT$READABLE returns a value of TRUE (OFFH) if the segment pointed to 
by selector is reachable and readable from the current privilege level; FALSE (0), if 
it is not. 

10.5.7.2 The SEGMENT$WRITABLE Function 

SEGMENT$WRITABLE is a built-in BYTE function. It is activated by a function 
reference with the form: 

SEGMENT$WRITABLE (selector); 
Where: 

selector is an expression with a SELECTOR value. 

SEGMENT$WRITABLE returns a value of TRUE (OFFH) if the segment pointed to 
by selector is reachable and writable from the current privilege level; FALSE (0), if it 
is not. 
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(continued) 

10.5.8 Adjusting the Requested Privilege Level ^ 

10.5.8.1 The ADJUST$RPL Function 

ADJUST$RPL is a built-in SELECTOR function that returns the argument of the 
adjusted requested privilege level (RPL). It is activated by a function reference with 
the form: 

ADJUST$RPL (selector); 
Where: 

selector is an expression with a SELECTOR value. 

If the requested privilege level (RPL) field of the argument selector is less than the 
RPL field of the code segment selector for the routine calling the procedure that 
invoked ADJUST$RPL, then the hardware ZERO flag is set and the value returned is 
the argument of an adjusted RPL field. Otherwise, the ZERO flag is reset, and the 
value returned is the original value of the argument. 

Setting the ZERO flag should be used with caution, see the note in Section 10.5.6. 1 . 

The following example illustrates how the ADJUST$RPL function can be used: 

P: PROCEDURE ( SEGMENT ) i 

DECLARE SEGMENT SELECTOR i 

SEGMENT = ADJUST5RPL ( SEGMENT ) i 
IF ZERO THEN 

/* The RPL of SEGMENT was less than the RPL of */ 
/* the routine that called Pi SEGMENT now has */ 

/* the RPL of the caller- */ 

ELSE 

/* The RPL of SEGMENT was not less than the RPL */ 
/* of the routine that called Pi SEGMENT is unchanged */ | 

END Pi 

end 

— PL/M-286/386 
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10.6 The REAL Math Facility 



REAL math support for PL/M is provided by the numeric coprocessor. In relation to 
the program, the REAL math facility consists of the following: 

• The REAL stack, used to hold operands and results during REAL operations. 

• The REAL error byte (see Figure 10-2), consisting of seven exception flags 
initialized to all 0s. (The reserved bit is set to 1 by the numeric coprocessor.) 

The first six bits in this byte correspond to the possible errors that can arise 
during REAL operations (see Appendix G). When an error occurs, the facility 
sets the corresponding bit to 1 . A program can invoke a built-in procedure (de- 
scribed in Section 10.7) that reads and clears the REAL error byte. 

The exception/error categories are discussed in Appendix G. 

• The REAL mode word (see Figure 10-3), consisting of 16 bits initialized to 
03FFH (or 7FFH for the 80387 numeric coprocessor). 

1 . Bits 0-7 determine whether the corresponding error condition is to be handled 
with the default recovery (described next) or with the programmer-supplied 
exception procedure (see Appendix G for details on writing these). When the 
bit is 1, the default is used; when it is 0, the user routine is used. In either 
case, the facility records the error by setting the corresponding bit of the 
REAL error byte. For most uses, the default recovery is appropriate and less 
work. 



IR 




PE 


UE 


OE 


ZE 


DE 


IE 



EXCEPTION FLAGS ( 1 EXCEPTION HAS OCCURRED) 

INVALID OPERATION 

DENORMALIZED OPERAND 

ZERODIVIDE 

OVERFLOW 

UNDERFLOW 

PRECISION 
(RESERVED) 

INTERRUPT REQUEST 121636-2 



Figure 10-2 The REAL Error Byte 
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RC 
—I— 



IEM 




PM 


UM 


OM 


ZM 


DM 


M 



EXCEPTION MASKS 1 1 EXCEPTION IS MASKED) 

INVALID OPERATION 

DENORMALIZED OPERAND 

ZERODIVIDE 

OVERFLOW 

UNDERFLOW 

PRECISION 
(RESERVED) 

INTERRUPT-ENABLE MASK (IEM) 
PRECISION CONTROL 
ROUNDING CONTROL 
INFINITY CONTROL 
(RESERVED) 



Interrupt-Enable Mask: 

Interrupts Enabled 

1 Interrupts Disabled (Masked) 

Precision Control: 

00 24 bits 

01 (reserved) 

10 53 bits 

11 64 bits 

Rounding Control. 

00 Round to Nearest or Even 

01 Round Down (toward ) 

10 Round Up (toward ) 

11 Chop (Truncate Toward Zero) 

Infinity Control: 

Projective 

1 Attine 



121636-3 



Figure 10-3 The REAL Mode Word 



This mode word is often called a mask; that is, it lets some signals through (to 
interrupt processing), but not others. If one of the bits 0-5 is a 0, the corres- 
ponding error is said to be unmasked (see Section 10.7 on how to set the mode 
word). 



The Target CPU and Numeric Coprocessor 



10-23 



If the interrupt is enabled (IEM = 0), one of the masked bits is 0, and the 
corresponding error occurs during floating point processing, then the REAL 
math facility interrupts the host CPU. The numeric coprocessor's interrupt 
number is dependent on the internal configuration. The exception condition is 
thus reported and control is passed to the user-written error handling routine. 
This situation is called an unmasked error. Section 8.5 and Appendix G dis- 
cuss aspects of interrupt procedures. 

Conversely, a masked error means the mode bit corresponding to that error is 
1 . Masked errors do not cause an interrupt, but are handled as described in 
Appendix G. 

Bits 13, 14, and 15 are reserved and are not for PL/M use. 

Bits 8-12 provide options for controlling precision, rounding, and infinity 
representation (see Figure 10-3). 

2. All intermediate results are held in an internal format of 64-bit precision. The 
most-significant 24 bits of the final result are returned (plus sign and 7-bit 
exponent) as the PL/M answer, and rounded, if needed, according to the 
user-specified control. The default precision setting preserves extended preci- 
sion and operates slightly faster than the other. 

3. Rounding introduces an error of less than one unit in the last place to which 
the result was rounded. Statistically, the default provides the most accurate 
and unbiased estimate of the true result (i.e., the 64-bit result). In all rounding 
modes except round down, subtracting a number from itself yields + 0; round 
down yields —0. 



00 




+O0 



PROJECTIVE CLOSURE 

121945-4 
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10.7 Built-lns Supporting the REAL Math Unit 
10.7.1 The 1NIT$REAL$MATH$UNIT Procedure 



INIT$REAL$MATH$UNIT is a built-in untyped procedure activated by a CALL 
statement, as follows: 

CALL INIT$REAL$l1ATH$UNITn 

This call is required as the first access to the REAL math facility (the numeric 
coprocessor). 

This call initializes the REAL math unit for subsequent operations. This includes 
setting a default value into the control (REAL mode) word, namely 03FFH in hex- 
adecimal or 0000001111111111 in binary. This setting masks all exceptions and in- 
terrupts, sets precision to 64 bits, and sets the rounding mode to even. This means no 
interrupts will occur from the REAL math facility regardless of what errors are 
detected. 

Procedures activated after this call has taken effect do not need to do such initial- 
ization. 



10.7.2 The SET$REAL$MODE Procedure 

This procedure should only be invoked to change the default mode word (for exam- 
ple, to unmask the invalid exception). 

SET$REAL$MODE is a built-in untyped procedure, activated by a CALL statement 
with the following form: 

CALL SET$REAL$MODE (modeword); 
Where: 

PL/M-86 PL/M-286 PL/M-386 

modeword expression with expression with expression with 

WORD value WORD value HWORD value 



The value of modeword becomes the new contents of the REAL mode word (see 
Figure 10-3). The suggested value for modeword is 033EH, (0000001100111110 in 
binary). This value provides maximum precision, default rounding, and masked han- 
dling of all exception conditions except invalid, which can alert the user to errors of 
initialization or stack usage. See Appendix G for facts and references on writing an 
interrupt handling procedure. 
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10.7.3 The GET$REAL$ERROR Function 

GET$REAL$ERROR is a built-in BYTE function activated by a function reference 
with the following form: 

GET$REAL$ERROR 

The BYTE value returned is the current contents of the REAL error byte (see Figure 
10-2). This function also clears the error byte in the REAL math facility. 

10.7.4 Saving and Restoring REAL Status 

If an interrupt procedure performs any floating-point operation, it will change the 
REAL status. If such an interrupt procedure is activated during a floating-point 
operation, the program will be unable to continue the interrupted operation cor- 
rectly after returning from the interrupted procedure. Therefore, it is first neces- 
sary for any interrupt procedure that performs a floating-point operation to save the 
REAL status and subsequently restore it before returning. The built-in procedures 
SAVE$REAL$STATUS and RESTORE$REAL$STATUS make this possible. 
SAVE$REAL$STATUS also initializes the numeric coprocessor. 

Additionally, these procedures can be used in a multi-tasking environment where a 
running task using the numeric coprocessor can be preempted by another task that 
also uses the numeric coprocessor. The preempting task must call SAVE$REAL- 
$STATUS before it executes any statements that affect the numeric coprocessor, that 
is, before calling SET$REAL$MODE and before any arithmetic or assignment of 
REALs (other than GET$REAL$ERROR, if needed). 

New vectors will be required for the interrupt handlers appropriate to each new task 
(e.g., to handle unmasked exception conditions). These vectors must be initialized by 
the operating system. 

After its processing is complete and it is ready to terminate, the preempting task must 
call RESTORE$REAL$STATUS to reload the state information that applied at the 
time the former running task was preempted. This enables that task to resume execu- 
tion from the point where it relinquished control. 

NOTE 

REAL functions without REAL parameters should not call GET$REAL$ 
ERRORS or SAVE$REAL$STATUS before executing at least one floating- 
point instruction. To do so may result in loss of processor synchronization. 
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10.7.4.1 The SAVE$REAL$STATUS Procedure 



SAVE$REAL$STATUS is a built-in untyped procedure activated by a CALL state- 
ment with the form: 

CALL SAVE$REAL$STATUS {location); 
Where: 

location is a pointer to a memory area (94 bytes for PL/M-86 and PL/M-286 
and 108 bytes for PL/M-386) where the REAL status information 
will be saved. 

The REAL status is saved at the specified location, and the REAL stack and error 
bytes are reinitialized. 

If the state of the REAL math unit is unknown to this procedure when it is called, as 
in the case previously mentioned for preempting tasks, then an initialization will 
destroy existing error flags, masks, and control settings. To avoid this, the appropriate 
action (except for error-recovery routines, discussed in Appendix G) is to issue: 

CALL SAVE$REAL$STATUS (aiocation_l) 5 

before any REAL math usage, and 

CALL RESTORESREALSSTATUS <aiocation_l) n 

prior to the procedure's return. The save automatically reinitializes the math unit and 
the error byte. 

This protects the status of preempted tasks or prior procedures and establishes a 
known initialization state for the current procedure's actions. The microprocessor 
interrupts are disabled during the save. 

NOTE 

The microprocessor must be able to acknowledge numeric coprocessor inter- 
rupts or loss of synchronization occurs. 

10.7.4.2 The RESTORE$REAL$STATUS Procedure 

RESTORE$REAL$STATUS is a built-in untyped procedure activated by a CALL 
statement with the form: 

CALL RESTORE$REAL$STATUS (location); 



The Target C PU and Numeric Coprocessor 



10-27 



Where 



location is a pointer to a memory area where the REAL status information was 
previously saved by a call to the SAVE$REAL$STATUS procedure. 

This procedure should be called prior to returning from an interrupt procedure where 
the real math unit's status was saved using SAVE$REAL $STATUS. 

PL/M-286/386 — 

10.7.5 Interrupt Processing 

10.7.5.1 The WAIT$FOR$INTERRUPT Procedure 

WAIT$FOR$INTERRUPT is a built-in procedure that is activated by a CALL state- 
ment with the form: 

CALL WAIT$FOR$INTERRUPT; 

This procedure is used to generate an IRET instruction in a nested interrupt task; if it 
is used elsewhere, the results are undefined. The IRET instruction causes the micro- 
processor to perform a task switch, saving the status of the outgoing task in its TSS. 
The next time the interrupt task is activated, execution will begin at the instruction 
immediately following the IRET, with all the registers unchanged. 

The following example illustrates how the WAIT$FOR$INTERRUPT procedure can 
be used: 

NEWSINTERRUPT: 

CALL INITIALIZE^INTERRUPT^LISTi 

/* Start of a list of interrupts */ 

DO WHILE li 

CALL UAIT$FOR$INTERRUPTi 

/* Wait for next interrupt within list */ 
CALL PROCESS$INTERRUPT=, 
IF END$OF$INTERRUPT$LIST THEN DOi 
CALL WAIT$FOR$INTERRUPTi 
/* Wait for start of next interrupt sequence */ 
■ GOTO NEW$INTERRUPT i 

END i 

I END i 

end 

PL/M-286/386 — 
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10.8 WORD16 Mapping for Built-lns 



PL/M-386 

I 



Table 10-1 lists the WORD 16 terminology for the built-ins described in this chapter 
that specify particular data types. In PL/M-386, WORD 16 keywords are mapped to 
the equivalent WORD32 keyword. The WORD32 terminology is repeated in this 
table. 



Table 10-1 WORD32/WORD16 Mapping for Built-ins 



WORD32 


WORD16 


INPUT 
OUTPUT 
BLOCKINPUT 
BLOCKOUTPUT 


INPUT 
OUTPUT 
BLOCKINPUT 
BLOCKOUTPUT 


INHWORD 
OUTHWORD 
BLOCKINHWORD 
BLOCKOUTHWORD 


INWORD 
OUTWORD 
BLOCKINWORD 
BLOCKOUTWORD 


IN WORD 
OUTWORD 
BLOCKINWORD 
BLOCKOUTWORD 


INDWORD* 
OUTDWORD* 
BLOCKINDWORD* 
BLOCKOUTDWORD* 



*The WORD1 6 control must be used. I 

end 

PL/M-386 
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COMPILER CONTROLS 

■PMHMMMMi inteT ™ 

11.1 Introduction to Compiler Controls 

You can control the operation of the PL/M compilers by using the compiler controls 
described in this chapter. You can use controls in the command that invokes the 
compiler, or as control lines in the source input file. 

A control line contains a dollar sign ($) in the left margin. Normally, the left margin 
is set at column one, but you can change this with the LEFTMARGIN control. Con- 
trol lines allow selective control over sections of the program. For example, it may be 
desirable to suppress the listing for certain sections of the program, or to cause page 
ejects at certain places. 

A line in a source file is considered to be a control line by the compiler if there is a 
dollar sign in the left margin, even if the dollar sign appears to be part of a PL/M 
comment or character string constant. Control lines within the source code must 
begin with a dollar sign and can contain one or more controls, each separated by at 
least one blank. Only the left margin column of a control line should contain a dollar 
sign. 

The following are examples of control lines: 

SNOCODE XREF 
REJECT CODE 

There are two types of controls: primary and general. Primary controls must occur 
either in the invocation command or in a control line that precedes the first noncon- 
trol line of the source file. Primary controls cannot be changed within a module. 
General controls can occur either in the invocation command or in a control line 
anywhere in the source input, and can be changed freely within a module. Certain 
controls can be negated by prefacing the control word with a NO. The control de- 
scriptions in this chapter indicate that option by showing both options in the headings. 
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Many controls are available, but a set of defaults is built into the compilers. The 
controls are summarized in alphabetic order in Table 11-1. Controls that are specific 
to PL/M-86 and -386 are summarized in Tables 1 1-1 A and 1 1-1B, respectively. 

A control consists of a control-name and, in some cases, a parameter. Parameters in 
control lines must be enclosed in parentheses. Enclosing control parameters on the 
invocation line in parentheses may be illegal, depending on the host operating 
system. 

This chapter is organized in the following manner: 

• Controls, default settings, abbreviations, and effects are listed in Table 11-1. 

• Compiler controls are categorized and an overview for each of the categories is 
provided. 

• Compiler control descriptions are provided in alphabetical order, as listed in 
Table 11-1. For example, the NOSYMBOLS description is located with the 
SYMBOLS description. 

• A sample program listing is provided with a description of the listing. 
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Table 11-1 Compiler Controls 



Control 


Default 


Abbrev. 


Effect 


CODE 
NOCODE 


NOCODE 


CO 

NOCO 


Enables or disables 
listing of pseudo- 
assembly code. 


COND 
NOCOND 


COND 


none 
none 


Determines whether 
text skipped during 
compilation appears 
in the listing. 


•DEBUG 
'NODEBUG 


NODEBUG 


DB 

NODB 


Generates debug 
records in the object 
module. 


EJECT 


paging is automatic 


EJ 


Forces a new print 
page. 


IF 

ELSEIF 

ELSE 

ENDIF 


not applicable 


none 


Enables the condi- 
tional comDilation 
capability by testing 
for conditions that 
use the value of 
compile-time 
switches. 


INCLUDE 


not applicable 


IC 


Includes other 
source files as input 
to the compiler. 


•INTERFACE 


none 


ITF 


Enables calls to 
other high-level 
languages and to 
source code 
translators. 


LEFTMARGIN 


LEFTMARGIN(I) 


LM 


Specifies that only 
input beginning at 
position n should be 
processed by the 
compiler. 


LIST 
NOLIST 


LIST 


LI 

NOLI 


Enables or disables 
listing of source 
program. 



* Denotes primary control 
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Table 11-1 Compiler Controls (continued) 



Control 


Default 


Abbrev. 


Effect 


♦OBJECT 
•NOOBJECT 


OBJECT 
(source. OBJ) 


OJ 

NOOJ 


Specifies a filename 
for an object mod- 
ule, or prevents 
creation of an object 
module. 


'OPTIMIZE 


OPTIMIZER ) 


OT 


Determines the 
optimization level 
during code 
generation. 


OVERFLOW 
NOOVERFLOW 


NOOVERFLOW 


OV 

NOOV 


Enables or disables 
overflow detection 
during signed 
arithmetic. 


*PAGELENGTH 


PAGELENGTH(60) 


PL 


Specifies the maxi- 
mum number of 
lines per page. 


*PAGEWIDTH 


PAGEWIDTH(120) 


PW 


Specifies the maxi- 
mum number of 
characters per line. 


PAGING 
NOPAGING 


PAGING 


PI 

NOPI 


Specifies whether 
the program listing 
should be page 
formatted with a 

hparlinn that iHpnti- 

fies the compiler 
and page number. A 
user-specified title 
can also be included 
(see TITLE). 


PRINT 
NOPRINT 


PRINT 


PR 

NOPR 


Enables or disables 
printed output, or 
selects the device or 
file to receive the 
printed output. 



* Denotes primary control 
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Table 11-1 Compiler Controls (continued) 



control 


ueiauit 


ADDrev. 


cTieci 


*RAM 


**RAM 


none 


Specifying RAM 


•ROM 






places the CON- 








STANT section 








within trie uaia 








^pnmpnt in all ^ipn- 








mpntation SnpHfv- 

1 1 IC 1 1 LC4 1 1 \J II' \JUwul 1 y 








inn ROM nlacps 

ii iy i i v — ' i v i yiuvco 








mn^tants in thp 

bWI IOIUI 1 lO III LI ICi 








CODE SGgment. 


SAVE 


none 


SA 


Enables the settings 


RESTORE 




RS 


of certain controls to 








hp ^avpd on thp 

L/C oavgU \J 1 1 LI IC 








ctar*U anrl rpctnroc 

oLcturx dl IU 1 CoLUI Co 








tho pnntrnl QottinriQ 
u ic uuiiuui octuiiyo 








aftpr thp inplnripri 

CM LCI LI IC IIIL>IUUCIJ 








file. 


O I — 1 


riLOL 1 \\Jf 


nnno 

1 IVJ 1 IC 


fnntrrtlQ the io nf 

WUMLIUlO LHC valUC vj 1 


RESET 






cwitrhp^ SFT p*5- 

ovvuui ico. o l_ i co 








tq hi i c hoc a to 
IctUiioiico a Value. 








RESET restores the 








value toO. 


*SMALL 


SMALL (PL/M-86 


SM 


Determines the 


"COMPACT 


and PL/M-386) 


CP 


spa mentation 


'MEDIUM 




MD 


model. 


•LARGE 


LARGE (PL/M-386) 


LA 




SUBTITLE 


no ^uhtitlp 


ST 


Put*? a *5iihtitlp on 

l U lo CI OUULIIIC L/l 1 








oarh nanp nf nrintprl 

CClLiI 1 (JCtyC L/l L/MI1LCLJ 








ontniit and ran^p^ a 

L/ULL/LIL CI I 1 Li UaUOCO a 








paqe eject. 


•SYMBOLS 


NOSYMBOLS 


SB 


Specifies to the 


•NOSYMBOLS 




NOSB 


compiler whether or 








not to produce a 








listing of identifiers 








and attributes. 



* Denotes primary control 

* In all cases excluding LARGE used with PL/M-86 and PL/M-286. In this case, ROM is the 
default. 
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Table 11-1 Compiler Controls (continued) 



Control 


Default 


Abbrev. 


Effect 


*TITLE 


module name in the 
source code 


TT 


Places a title on 
each page of the 
printed output. 


TYPE 
*NOTYPE 


TYPE 


TY 

NOTY 


Specifies whether or 
not to include type 
records in the object 
module. 


*XREF 
*NOXREF 


NOXREF 


XR 

NOXR 


Enables or disables 
a cross-reference 
listing of source 
program identifiers. 



* Denotes primary control 



Table 11-1A PL/M-86 Specific Compiler Controls 



Control 


Default 


Abbrev. 


Effect 


*INTVECTOR 
*NOINTVECTOR 

*MOD86 
*MOD186 


INTVECTOR 
MOD86 


IV 

NOIV 
none 


Enables or disables an inter- 
rupt vector. 

Specifies a compiler gener- 
ated set of microprocessor- 
specific instructions. 



* Denotes primary control 



Table 11-1B PL/M-386 Specific Compiler Controls 



Control 


Default 


Abbrev. 


Effect 


*WORD16 
*WORD32 


WORD32 


W16 

W32 


Defines the data type terminology. 



* Denotes primary control 



11.1.1 Input Format Control 

LEFTMARGIN 

The LEFTMARGIN control specifies the left margin of the source file. 
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1 1 .1 .2 Code Generation and Object File Controls 

These controls determine what type of object file is to be produced and in which 
directory it is to appear. Object file controls include the following: 

DEBUG/NODEBUG 
INTERFACE 

INTVECTOR/NOINTVECTOR 
MOD86/MOD186 (for PL/M-86 only) 
OBJECT/NOOBJECT 
OPTIMIZE 

OVERFLOW/NOOVERFLOW 
RAM/ROM 

SMALL/COMPACT/MEDIUM/LARGE 
TYPE/NOTYPE 

WORD32/WORD16 (for PL/M-386 only) 



11.1.3 Object Module Sections 

The output of a PL/M compiler is an object file containing a compiled module. This 
object module may be linked with other object modules using the appropriate linker 
or binder. A knowledge of the makeup of an object module is not necessary for PL/M 
programming, but can aid in understanding the controls for program size and 
linkage. 

— PL/M-86 

The object module output by the PL/M-86 compiler contains five sections: l 

• Code Section 

• Constant Section (absent in LARGE and in ROM) 

• Data Section 

• Stack Section 

• Memory Section 



I 

end 

PL/M-86 
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PL/M-286/386 — 

Object modules output by the PL/M-286 and -386 compilers contain three sections: 

• Code Section 

• Data Section 

• Stack Section 

I These sections can be combined in various ways into memory segments for execu- 
tion, depending on the size of the program. 

end 

PL/M-286/386 — 



11.1.3.1 Code Section 

This section contains the instruction code generated for the source program. If either 
the LARGE control or the ROM control is used, this section also contains all vari- 
ables initialized with the DATA attribute, all REAL constants, and all constant lists. 
(The LARGE control is specific to PL/M-86 and PL/M-286. For upward compatibil- 
ity, the LARGE control is included in PL/M-386. However, it functions exactly like 
the COMPACT control.) 

In addition, the code section for the main program module contains a main program 
prologue generated by the compiler. This code precedes the code compiled from the 
source program, and sets the CPU up for program execution by initializing various 
registers (and, for the 8086 microprocessor, enabling interrupts). 

PL/M-86 — 

11.1.3.2 Constant Section 

This section contains all variables initialized with the DATA attribute, as well as all 
REAL constants and all constant lists. If the LARGE or ROM controls are used, this 
information is placed in the code section and no constant section is produced. 
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11.1.3.3 Data Section 



All variables are allocated space in this section with the exception of para- 
meters, based variables, and variables located with an AT attribute or local to a 
REENTRANT procedure. (For PL/M-86, this section also excludes variables initial- 
ized with the DATA attribute.) If the RAM control is used, this section also contains 
all variables initialized with the DATA attribute, as well as all REAL constants and all 
constant lists. 

If a nested procedure refers to any parameter of its calling procedure, then all param- 
eters of that calling procedure will be placed in the data section during execution. The 
compiler reserves enough space during compilation to prepare for this. 

11.1.3.4 Stack Section 

The stack section is used in executing procedures, as explained in Appendixes F and 
G. It is also used for any temporary storage used by the program but not explicitly 
declared in the source module (such as temporary values generated by the compiler). 

The exact size of the stack is automatically determined by the compiler except for 
possible multiple invocations of reentrant procedures. You can override this computa- 
tion of stack size and explicitly state the stack requirement during the combining 
process. 

NOTE 

When using reentrant procedures or interrupt procedures, be sure to allocate a 
stack section large enough to accommodate all possible storage required by 
multiple invocations of such procedures. The stack size can be explicitly speci- 
fied during the module combining process. 

The stack space requirement of each procedure is shown in the listing produced 
by the SYMBOLS or XREF control. This information can be used to compute 
the additional stack space required for reentrant or interrupt procedures. 
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PL/M-86 — 

11.1.3.5 Memory Section 



1 



end 

PL/M-86 



This is the area of memory referenced by the built-in PL/M-86 identifier MEMORY. 
Its maximum allowable size depends on the size control used in compilation 
(SMALL, COMPACT, MEDIUM, or LARGE) as explained in the following section. 

The compiler generates a memory section of length zero, and it is your responsibility 
to specify the actual (run-time) space required during the module combining process. 



11 .1 .4 Segmentation Controls 
PL/M-86/286 — 

I For PL/M-86 and PL/M-286, these controls specify the memory size requirements of 
the program containing the module to be compiled. They affect the operation of the 
compiler in various ways and impose certain constraints on the source module being 
compiled. 

These controls also influence how locations are referenced in the compiled program, 
which leads to certain programming restrictions for each size control. 

Note that for maximum efficiency of the object code, the smallest possible size 
should be used for any given program. Also note that all modules of a program 
should be compiled with the same size control. These are primary controls. They 
have the form: 

SMALL 
COMPACT 
MEDIUM 
LARGE 

l Extensions to these controls (i.e., the use of subsystems) are discussed in Chapter 13. 

end 

PL/M-86/286 — 
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PL/M-386 

For PL/M-386, the segmentation controls influence how locations are referenced in I 
the compiled program, which leads to certain programming restrictions for each of 
the segmentation controls. These are primary controls. They have the following 
form: 

SMALL 
COMPACT 
MEDIUM 
LARGE 

The segmentation controls SMALL and COMPACT determine the maximum allow- 
able size of the segments produced in the object program as well as the grouping of 
object types (code, data, constants, and stack). These controls affect the operation of 
the compiler in various ways and impose certain constraints on the source module 
being compiled. 

The MEDIUM control is equivalent to the SMALL control. The LARGE control is 
equivalent to the COMPACT control except when LARGE is used to indicate a sub- 
system whose name is unknown at compile time (see Section 13.4). 

For maximum efficiency of the object code, the smallest possible size should be used 
for any given program. Also, all modules of a program should be compiled with the 
same segmentation control. 

The segmentation controls are described later in this chapter (see Section 1 1.2.22); 
extensions to these controls (i.e., the use of subsystems) are described in Chapter 13. 

end 

— PL/M-386 



1 1 .1 .5 Listing Selection and Content Controls 

These controls determine what types of listings are produced and where they appear. 
The controls are as follows: 

CODE/NOCODE 

LIST/NOLIST 

PRINT/NOPRINT 

SYMBOLS/NOSYMBOLS 

XREF/NOXREF 
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1 1 .1 .6 Listing Format Controls 



Format controls determine the format of the listing output of the compiler. These 
controls are as follows: 

EJECT 

PAGELENGTH 

PAGEWIDTH 

PAGING/NOPAGING 

SUBTITLE 

TITLE 

1 1 .1 .7 Source Inclusion Controls 

With these controls, the input source can be changed to a different file. The con- 
trols are: 

INCLUDE 
SAVE/RESTORE 

11 .1 .8 Conditional Compilation Controls 

These controls cause selected portions of the source file to be skipped by the compiler 
if specified conditions are not met. Figure 11-1 shows an example program using 
conditional compilation and Figure 1 1 -2 shows the same example program using the 
NOCOND control. 

The conditional compilation controls are: 

COND/NOCOND 

IF/ELSEIF/ELSE/ENDIF 

SET/RESET 
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PL/M-flt, COMPILER EXAMPLE 



mm/dd/yy hh'-min'-ss PAGE 1 



system-id PL/n-fib Vx-y COMPILATION OF MODULE EXAMPLE 
OBJECT MODULE PLACED IN cex-obj 

COMPILER INVOKED BY: plmSb cex-src PU(7fl) SET(DEBUG=3) 



1 




EXAMPLE: DOi 


2 


i 


DECLARE BOOLEAN LITERALLY ' BYTE ' i TRUE LITERALLY ' DFFH ' < 






FALSE LITERALLY 'Q'\ 


3 


i 


PRINTSDIAGNOSTICS: PROCEDURE (SWITCHES-, TABLES) EXTERNALS 


4 


2 


DECLARE ( SWITCHES -, TABLES) BOOLEANi 


S 


5 


END PRINT$DIAGNOSTICS=, 


b 


2 


DISPLAYSPROMPT: PROCEDURE EXTERNALS END DISPLAY$PROMPT ■■, 


a 


2 


AUAITSCR: PROCEDURE EXTERNAL i END AUAIT$CR \ 



$IF DEBUG = 1 

CALL PRINTSDIAGNOSTICS (TRUE-, FALSE) \ 
$ RESET (TRAP) 
5ELSEIF DEBUG = 2 

CALL PRINTSDIAGNOSTICS (TRUE-, TRUE ) i 
$ RESET (TRAP) 
$ELSEIF DEBUG = 3 
ID 1 CALL PRINTSDIAGNOSTICS (TRUE-, TRUE) i 

11 1 CALL PRINTSDIAGNOSTICS (TRUE-, TRUE):, 

$ SET (TRAP) 
SENDIF 

$IF TRAP 

12 1 CALL DISPLAYSPROMPT; 

13 1 CALL AWAIT$CRi 

$ENDIF 

14 1 END EXAMPLE; 

MODULE INFORMATION: 

CODE AREA SIZE = DD17H 
CONSTANT AREA SIZE = DDODH 
VARIABLE AREA SIZE = DDDDH 
MAXIMUM STACK SIZE = OODbH 
3D LINES READ 
D PROGRAM WARNINGS 
D PROGRAM ERRORS 

DICTIONARY SUMMARY : 

4KB MEMORY USED 
DKB DISK SPACE USED 

END OF PL/M-flt COMPILATION 



23D 
DD 
DD 
LD 



Figure 11-1 Sample Program Using Conditional Compilation (SET Control) 
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PL/M-flb COMPILER EXAMPLE mm/dd/yy hh:mm:ss PAGE 1 

system-id PL/M-flt. Vx-y COMPILATION OF MODULE EXAMPLE 
OBJECT MODULE PLACED IN cex-obj 

COMPILER INVOKED BY: plmflb cex-src Plii(7fl) SET(DEBUG=3) NOCOND 

1 EXAMPLE: DOi 

2 1 DECLARE IS LITERALLY 'LITERALLY ' i BOOLEAN IS 'BYTE'-, TRUE IS ' QFFH ' i 

FALSE IS *Q'i 

3 1 PRINTSDIAGNOSTICS: PROCEDURE (SUITCHESn TABLES) EXTERNAL; 

4 2 DECLARE ( SWITCHES n TABLES) BOOLEAN i 

5 2 END PRINTIDIAGNOSTICSi 

L 2 DISPLAYSPROMPT: PROCEDURE EXTERNAL; END DISPLAY$PROMPT^ 

fi 2 AldAITSCR: PROCEDURE EXTERNAL i END AWAIT^CR 1 , 

IIP DEBUG = 1 
SELSEIF DEBUG = 3 
ID 1 CALL PRINT$DIAGNOSTICS (TRUEn TRUE) i 

11 1 CALL PRINTSDIAGNOSTICS (TRUE-, TRUE) i 

* SET (TRAP) 
IENDIF 

•IF TRAP 

12 1 CALL DISPLAYSPROMPTi 

13 1 CALL AUAIT$CRi 

*ENDIF 

14 1 END EXAMPLE, 

Figure 11-2 Sample Program Showing the NOCOND Control 
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11 .1 .9 Language Compatibility Control 



INTERFACE 

This control enables PL/M to call procedures written in other languages and vice 
versa. For PL/M-386, this control also enables the use of external procedures com- 
piled with a PL/M-286 compiler (or other 286-OMF compiler). 

11.1.10 Predefined Switches 

If one of the switch names (in the following list) appears in an IF or ELSEIF condi- 
tion and has not been explicitly assigned a value using the SET or RESET control, its 
default value is its primary control value. (WORD 16 and WORD32 are specific to 
PL/M-386.) 

SMALL MEDIUM RAM WORD 16 
COMPACT LARGE ROM WORD32 

If a predefined switch is assigned a value using the SET or RESET control, it func- 
tions from that point on like any other switch. A primary control value is not affected 
by setting or resetting the predefined switch with the same name. 

The four model switches are distinct. Even though the primary controls SMALL and 
MEDIUM have the same control interpretation, specifying the MEDIUM control sets 
the MEDIUM switch only, and specifying the SMALL control sets the SMALL 
switch only (similarly for COMPACT and LARGE). 

For example, given the following sequence of PL/M-386 control lines: 

SRAM UORDlb MEDIUM \ line 1 
$IF RAM =, line S 

SELSEIF U0RD32 

5ELSEIF SMALL 

5ENDIF 

$SET (SMALL-, U0RD32 ) % line x 

At line 2, the switches RAM and WORD 16 are true and their counterparts ROM and 
WORD32 are false. The switch MEDIUM is true and the switches SMALL, 
COMPACT, and LARGE are false. Therefore, the IF condition is true and the two 
ELSEIF conditions are false. After line x, the switches RAM, WORD16, MEDIUM, 
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SMALL, and WORD32 are true; ROM, COMPACT, and LARGE remain false. The 
setting of SMALL and WORD32 compile time switches (whether set or reset) does 
not effect the existing segmentation control or any of the other switches. 

11 .2 Compiler Control Encyclopedia 

The following sections present each of the PL/M compiler controls. Note that the 
segmentation controls are grouped under the SMALL control. 

11.2.1 CODE/NOCODE 

Form CODE 

NOCODE 

Default NOCODE 

Type General 

Discussion 

The CODE control specifies that listing of the generated object code in pseudo- 
assembly language format is to begin. This listing is placed at the end of the program 
listing in the listing file. Note that the CODE control cannot override a NOPRINT 
control. 

The NOCODE control specifies that listing of the generated object code is to be 
suppressed until the next occurrence, if any, of a CODE control. 

11.2.2 COND/NOCOND 

These controls determine whether text within an IF element will appear in the listing 
if it is skipped during compilation. 

Form COND 

NOCOND 

Default COND 

Type General 
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Discussion 



The COND control specifies that any text that is skipped is to be listed (without 
statement or level numbers). Note that a COND control cannot override a NOLIST or 
NOPRINT control, and that a COND control will not be processed if it is within text 
that is skipped. 

The NOCOND control specifies that text within an IF element that is skipped is not to 
be listed; however, the controls that delimit the skipped text will be listed. This 
provides an indication that something has been skipped. Note that a NOCOND con- 
trol will not be processed if it is within text that is skipped. 

Figure 11-1 shows an example in which the program was compiled using the COND 
(by default) and SET controls with the SET switch assignment DEBUG = 3. Figure 
11-2 is the same program, but it was compiled using the NOCOND control (see 
Section 11.1.8). These figures demonstrate the use of conditional compilation. See 
also the description of SET/RESET. 

11.2.3 DEBUG/NODEBUG 

Form DEBUG 

NODEBUG 

Default NODEBUG 

Type Primary 

Discussion 

The DEBUG control specifies that the object module is to contain the statement 
number and relative address of each source program statement, information about 
each local symbol (including based symbols and procedure parameters), and block 
information for each procedure. This information may be used later by a debugging 
tool, such as PSCOPE. 

NOTE 

OPTIMIZE(O) is the only level of optimization that does not optimize code 
between program lines. Thus, it is the only one that gives guaranteed results 
when debugging programs. 
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11.2.4 EJECT 



Form EJECT 
Default None 
Type General 

Discussion 

EJECT stops printing on the current page and starts a new page of printed output. 

11.2.5 IF/ELSE/ELSEIF/ENDIF 

These controls provide conditional compilation capability based on the values of 
switches. 

These controls cannot be used in the invocation of the compiler, and each must be the 
only control on its control line. There are no default settings or abbreviations for 
these controls. 

An IF control and an ENDIF control delimit an IF element, which can have several 
different forms. The simplest form of an IF element is: 

$IF condition 
text 

$ENDIF 

Where: 

condition is a limited form of a PL/M expression in which the only valid 
operators are OR, XOR, NOT, AND, < , <=, =, < >, >=. 
and > , and the only valid operands are switches and whole-number 
constants with a range of to 255. If the switch does not appear in a 
SET control, a value of false (0) is assumed (except for predefined 
switches). Parenthesized subexpressions cannot be used. Within 
these restrictions, condition is evaluated according to the PL/M 
rules for expression evaluation. Note that condition must be fol- 
lowed by an end-of-line. 

text is text that will be processed normally by the compiler if the least 

significant bit of the value of condition is a 1 , or skipped if the bit is 
a 0. Note that text can contain any mixture of PL/M source and 
compiler controls. If the text is skipped, any controls within it are 
not processed. 
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The second form of the IF element contains an ELSE element: 



$IF condition 
text 1 
$ELSE 
text2 
$ENDIF 

In this construction, text 1 will be processed if the least significant bit of the value of 
condition is a 1 , and text 2 will be skipped. If the bit is a 0, text 1 will be skipped and 
text 2 will be processed. 

Only one ELSE control can be used within an IF element. 

With the most general form of the IF element, one or more ELSEIF controls can be 
introduced before the ELSE (if any): 

$IF condition 1 
text 1 

$ELSEIF condition 2 
text 2 

$ELSEIF condition 3 
text 3 



$ELSEIF condition n 

text n 

$ELSE 

text n+1 

$ENDIF 

where any of the ELSEIF elements can be omitted, as can the ELSE element. 

The conditions are tested in sequence. As soon as one of them yields a value with a 1 
as its least significant bit, the associated text is processed. All other text in the IF 
element is skipped. If none of the conditions yields a least significant bit of 1 , the text 
in the ELSE element (if any) is processed and all other text in the IF element is 
skipped. 

Parentheses cannot be used on a conditional control line. For example: 
*IF A+CB+C) 

is illegal. 
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11.2.6 INCLUDE 



Form 



INCLUDE (pathname) 



Default None 



Type 



General 



Discussion 



An INCLUDE control must be the right-most control in a control line or in the 
invocation command. 

The INCLUDE control causes the specified file to be included during compilation. 
Input continues from this file until an end-of-file is detected, and then processing 
resumes in the file containing the INCLUDE control. 

An included file may also contain INCLUDE controls. Note that such nesting of 
included files cannot exceed the depth as given in Appendix B. 



In PL/M-86 and PL/M-286, INTERFACE is a primary control that enhances the 
compatibility of PL/M with other programming languages. The INTERFACE control 
enables PL/M programs to call procedures written in other languages. Additionally, 
with the INTERFACE control, procedures written in PL/M can be called by proce- 
dures written in other languages. The calling conventions for procedures written in 
Pascal, Fortran, and PL/M are identical; therefore, the only language that needs a 
special designation for its calling convention is C. 

This control has the following form: (Note that INTERFACE cannot be part of an 
invocation command.) 

Form INTERFACE (lang = namel [...]) 
Default None 
Type Primary 



11.2.7 INTERFACE 
PL/M-86/286 — 
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— PL/M-86/286 

(continued) 

Where: 

lang is the name of the language that requires a different calling convention ■ 
for procedures; in this case, the language is C. Specifying INTERFACE 
for a language other than C has no effect; the standard calling conven- 
tion for PL/M will be used. 

name represents the procedure or data structure that will be called or refer- 
enced from the PL/M program. The compiler generates code that en- ■ 
ables procedures to be called according to the calling convention of the 
specified language. end 

— PL/M-86/286 



— PL/M-386 

For PL/M-386, INTERFACE is a primary control that enables PL/M-386 programs 
to call or be called by procedures written in C-386 and C-286, or procedures com- 
piled with an 80286 translator (specifically PL/M-286, Fortran-286, Pascal-286, and 
ASM286). 

This control has the following form: (Note that INTERFACE cannot be part of an 
invocation command.) 

Form INTERFACE (lang [/machine [/model [/ramrom] ] ] [ = id lid]. . .] ) 
Default None 



Type Primary 
Where: 

lang is C, the name of the language that requires a different calling con- 

vention for procedures. 

machine is 386 when calling C-386, and 286 when calling languages com- 
piled using an 80286 translator. Only references to 286 ids from 386 
modules are supported; 386 ids cannot be referenced from 286 mod- 
ules. Therefore, if machine is 286 then all the identifiers in the id list 
must be declared EXTERNAL. If MACHINE is 286 and an id is 
PUBLIC, it is an error. 
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PL/M-386 — 

(continued) 

model is SMALL, COMPACT, MEDIUM, or LARGE and defines the 
' model of segmentation for the specified ids. model determines 

whether 286 POINTER variables are offset-only or selector-offset, 
as defined by the PL/M-286 models of segmentation (see Chapter 
13, Table 13-1). If machine is 286, model defaults to LARGE, model 
should be specified as the same model of segmentation used to com- 
pile the 80286 code being referenced. If machine is 386, model is 
ignored. 

ramrom is RAM or ROM and defines the placement of constant variables in 
either the code or data segment. When used with the model SMALL, 
ramrom also defines whether POINTER variables are offset-only or 
selector-offset. The default is RAM unless model is LARGE, in 
which case the default is ROM. ramrom is ignored if machine is 386. 

id specifies the procedures and variables that are implemented using the 

specified language interface convention. 

Discussion 

When the INTERFACE control is used to call procedures compiled with an 80286 
translator, the program switches from using 32-bit stack offsets to 16-bit offsets. 
Therefore, the stack pointer for the called procedure must point within the lowest 
64K of the stack segment, or else a gate must be used to switch to such a stack 
segment. Parameters must fit within this boundary as well. 

The calling conventions for the 80386 languages (except C-386) are identical to 
PL/M-386 and therefore do not require the use of the INTERFACE control. Because 
the calling conventions differ for C-386, INTERFACE must be used to call or to be 
called from C-386 procedures. The C interface convention differs from the PL/M 
calling convention in the following ways: 

• Parameters are evaluated and pushed onto the stack in the reversed manner. 

• 8- and 16-bit parameters are zero extended or sign extended to 32 bits. 

• Real parameters for C are always 64-bit double floating-point numbers and are 
passed on the 80386 stack. 

• The caller clears the parameters off the stack after return and the callee does not 
pop parameters off the stack. 
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PL/M-386 

(continued) 



The following example demonstrates the use of the INTERFACE control to call a 
PL/M-286 procedure: 
SWORDlb 

^INTERFACE (PLn/5flb/SI1ALL/R0n = EX AMP) 

EXAMP: PROCEDURE ( A n B) EXTERNAL * 

DECLARE A WORD-, B POINTER; 
END EXAI1P; 

DECLARE X U0RD-, Y POINTER', 
CALL EXAI1P(X-,Y) ; 



In the preceding example, the INTERFACE control specifies the procedure EXAMP 
to be defined as an 80286-compatible. The actual parameters X and Y will be auto- 
matically converted to a 16-bit WORD and a 32-bit 80286 POINTER, respectively. 

The next example demonstrates calling a C-386 procedure: 

*INTERFACE(C/3flb=f oo) 
foo: procedure ( a n b -i c ) i 

declare (a-ib-ic) integer, end; 
declare (x-ijik) integer; 

call foo (ii jik)i 

In this example, INTERFACE specifies the procedure "foo" to be defined in an 
80386-compatible segment using the C calling conventions. The compiler automati- 
cally pushes the actual parameters in the correct order for the C procedure. 

Because Intel's C language requires that all 8- and 16-bit integer parameters be 
passed as 32-bit values, formal parameters of C-386 procedures should be declared as 
32-bit PL/M types: WORD or INTEGER. In this way, the PL/M-386 compiler will 
convert all actual parameters to the type expected by the C-386 code or passed from 
the C-386 code. 
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PL/M-386 — 

(continued) 

80286 variables and formal parameters of 80286 procedures should be declared the 
same as in the 80286 code. The PL/M-386 compiler is able to interpret the terms in 
an 80286 context and perform the following mapping: 



Term Used 


Maps to Data Type 


BYTE 


8-bit, unsigned 


HWORD 


8-bit, unsigned 


WORD 


16-bit, unsigned 


DWORD 


32-bit, unsigned 


QWORD 


32-bit, unsigned 


CHARINT 


8-bit (interpretation dependent on 80286 code) 


SHORTINT 


8-bit (interpretation dependent on 80286 code) 


INTEGER 


16-bit, signed integer 


LONGINT 


32-bit (interpretation dependent on 80286 code) 


REAL 


32-bit, real 


SELECTOR 


16-bit, selector 


POINTER 


see the following paragraphs 


OFFSET 


16-bit, unsigned 



An 80286-style long POINTER (32 bits composed of a 16-bit selector and a 16-bit 
offset), is a data type not defined in the PL/M-386 language. The PL/M-386 com- 
piler converts 48-bit 80386-style long POINTERS to 80286 POINTERS by truncating 
the offset portion to 16 bits. In SMALL RAM, a POINTER is the same as an 
OFFSET, and is treated as such by the compiler. 

I Note that this mapping is independent of WORD16/WORD32 (defined in Tables 9-3, 
10-1, and 11-3). This means that there is a third mapping of scalar terms to scalar 
data types. 

end 

PL/M-386 — - 
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11.2.8 IINTVECTOR/NOINTVECTOR 

Form INTVECTOR 

NOINTVECTOR 

Default INTVECTOR 

Type Primary 

Discussion 

Under the INTVECTOR control, the compiler creates an interrupt vector consisting 
of a 4-byte entry for each interrupt procedure in the module. For interrupt n, the 
interrupt vector entry is located at absolute location 4*n. See Chapter 8 and Appendix 
G for further discussion about procedures and interrupt processing. 

Alternatively, it may be desirable to create the interrupt vector independently, using 
either PL/M-86 or assembly language. In this case, the NOINTVECTOR control is 
used and the compiler does not generate an interrupt vector. The implications of this 
are discussed in Appendix G. 

end 

PL/M-86 



11.2.9 LEFTMARGIN 

This is the only control for specifying the format of the source input. 
Form LEFTMARGIN(n) 
Default LEFTMARGIN(I) 
Type General 

Discussion 

All characters to the left of position n on subsequent input lines are not processed by 
the compiler (but do appear on the listing). The first character on a line is in column 1. 



PL/M-86 

I 
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The new setting of the left margin takes effect on the next input line. It remains in 
effect for all input from this source file and any related INCLUDE files until it is 
reset by another LEFTMARGIN control. 

Note that a control line is one that contains a dollar sign in the column specified by 
the most recent LEFTMARGIN control. 

11.2.10 LIST/NOLIST 

Form LIST 

NOLIST 

Default LIST 

Type General 

Discussion 

The LIST control specifies that listing of the source program is to resume with the 
next source line read. Note that the LIST control cannot override a NOPRINT con- 
trol. If NOPRINT is in effect, no listing is produced. 

The NOLIST control specifies that listing of the source program is to be suppressed 
until the next occurrence, if any, of a LIST control. 

When LIST is in effect, all input lines (from the source file or from an INCLUDE 
file), including control lines, are listed, provided there is not a NOPRINT control in 
effect. When NOLIST is in effect, only source lines associated with error messages 
are listed. 

PL/M-86 

11.2.11 MOD86/MOD186 

Form MOD86 
MOD186 

Default MOD86 

Type Primary 
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PL/M-86 

(continued) 



Discussion 



The MOD86 control specifies that the object module will contain instructions for 
execution on the 8086 microprocessor. 

The MOD 186 control enables the compiler to generate an extended set of instructions 
in the object module for use on the 80186 microprocessor. 

This control must be specified when using the block I/O procedures described in 
Chapter 9 (see Section 9.4.8). 

end 

— PL/M-86 



11.2.12 OBJECT/NOOBJECT 

Form OBJECT (pathname) 
NOOBJECT 

Default OBJECT(sourcefftename.OBJ) 

Type Primary 

Discussion 

The OBJECT control specifies that an object module is to be created during compila- 
tion. The pathname is a standard host operating system pathname that specifies the 
file to receive the object module. If the control is absent or if an OBJECT control 
appears without a pathname, the object module is directed to a file that has the same 
name as the source input file, but with the extension .OBJ. 

The NOOBJECT control specifies that no object module is to be produced. 
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11.2.13 OPTIMIZE 



This control governs the level of optimization to be performed in generating object 
code. The n shown in the syntax represents the various levels of optimization, rang- 
ing from zero (the lowest) to three (the highest). Figures 11-3 to 11-6 illustrate the 
different levels of optimization. The same program was run for each level, but, the 
source file was printed only for OPTIMIZE (0). 

Form OPTIMIZE(n) 

Where: n = (0, 1 , 2, 3) 

Default OPTIMIZE (1) 

Type Primary 

Discussion 

OPTIMIZE (0). OPTIMIZE(O) specifies only folding of constant expressions. 

Folding means recognizing, during compilation, operations that are superfluous or 
combinable, and removing or combining them so as to save memory space or execu- 
tion time. Examples include addition with a zero operand, multiplication by one, and 
logical expressions with true or false constants. 

OPTIMIZE(O) is the only level of optimization that is guaranteed to not optimize 
code between lines. 

Figure 11-3 illustrates the OPTIMIZE (0) level of optimization. 



11-28 



Compiler Controls 



PL/n-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mm:ss PAGE 1 

system-id PL/M-flb Vx.y COMPILATION OF MODULE EXAMPLES_OF_OPTIMIZATIONS 
OBJECT MODULE PLACED IN example . obj 

COMPILER INVOKED BY: plmflb example. src Pld(7fl) COMPACT CODE OPTIMIZE(O) 

1 EXAMPLES_OF_OPTIMIZATIONS: DOi 

2 1 DECLARE (A-.B-.C) UORD-, 

D(IDO) WORD, 
(PTR_1, PTR_2) POINTER, 
ABASED BASED PTR_1 (10) LIORDi 

3 1 DO WHILE D(A+B) < DtA+B+m 

4 2 IF PTR_P1 < PTR_2 THEN DO; 
h 3 A = A * 2i 

7 3 ABASED(A) = ABASED(B) i 

fl 3 ABASED(B) = ABASED(C) i 

1 3 END i 

10 5 ELSE A = A + li 

11 2 END n 

12 1 END EXAMPLES_OF_OPTIMIZATIONSi 

; STATEMENT # 3 



0000 


6BEC 


MOV 


BPiSP 


0002 


FB 


STI 






31: 






0003 


flBlEOOOO 


MOV 


BX-iA 


0007 


031E0200 


ADD 


BXnB 


OOOB 


D1E3 


SHL 


BX-,1 


OOOD 


flB3b00OD 


MOV 


ST-.A 


0011 


0331,0200 


ADD 


SI-iB 


0015 


4b 


INC 


SI 


001b 


DIEb 


SHL 


SI-il 


ooia 


SBfl70b00 


MOV 


AX,D[BX] 


001C 


3Bfl40b00 


CMP 


AX-,D[SI] 


0020 


7203 


JB 


$ + 5H 


D022 


E17C00 


JMP 


32 


002S 


C40bCE00 


LES 


1 

AXnPTR_l 


0021 


B104 


MOV 


CL-.4H 


002B 


flCCb 


MOV 


SI-.ES 


002D 


flBDO 


MOV 


DXiAX 


002F 


D3EA 


SHR 


DXnCL 


0031 


03F2 


ADD 


SIiDX 


0033 


S1E00FO0 


AND 


AXtOFH 


0037 


C41bD200 


LES 


DXtPTR_2 


003B 


B104 


MOV 


CL n 4H 



Figure 11-3 Sample Program Showing the OPTIMIZE(O) Control 
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PL/M-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mn>:ss PAGE 5 

ASSEMBLY LISTING OF OBJECT CODE 



U U 3 V 


OLL f 


M AU 
1 1 V V 


V X. t Ld 


nn if 

UU Jr 


AD. ft A 


MAW 


r Y I\ Y 


nnui 

UU 4 J) 




inf\ 


ry n 


UU 4 3 


u dr d 


Ann 
A V v 


J/1 i DA 


nn a c 

UU4 3 


at r^nFnn 
□ ii L c U r UU 


A M IS 


Da i Ur H 


nnu q 


jOi r 




i 1 1 J/1 


nn Li d 

UU 4 D 


r jUc 


1 M 7 


4+ Li U 


n n u t\ 

UU 4 J/ 


3DIC 




AY T\ Y 


nn Li f 
UU 4 r 


~> Li n "3 
r 4Ud 


1 7 




UUbJi 


[■□hi nn 


1 M □ 

Jnr 


flJd 








t i i a 1 1 n t N 1 


UUi4 


npninnnn 
□□UbUUUU 


MA If 

ny v 


AY A 
A A i A 


U LJ b □ 


t,i m 
VJitU 


inl_ 


AY 1 
A A i 1 


U LJ 3 A 


ARnLnnnn 

O \ U bUUUU 


MA 11 
It \J V 


A AY 
A n A A 








t i 1 A 1 t rl t 111 1 




□ □ JjLUcUU 


MAN 

no v 


D Y □ 


nni □ 
UUbc 


1/jjLd 


iHL 


□ V 1 
DA 1 1 


nni 1 1 
UUbM 


n □ 3 i nnnn 
obdbUUUu 


M A U 

ny v 


il t A 


nni a 
UUbo 


i\i n 


iHL 


ry i 
il i 1 


nni a 
UUb A 


L4 JLLLUU 


L L i 


1\ T DTD 1 

1)1 1 r 1 K_Jj 


nn l r 

U LI b L 


CbODU Jj 


MAW 
II V V 


AY r^MRYl ADA^rnfTlTl 
AAiLi • [D A] • ABAit.l/11/lJ 


nmi 
UU r Jj 


L4 Jjtv_tUU 


i rr 
LLi 


DV DTD 1 

da i r 1 r< L 


UU f 3 


cbonuu 


MAN 

ny v 


Li - [b a J ■ AbAiLl/lilJi A a 








t iTATEnLNT 


nn ~> a 
UU r □ 


ob JjLUHUU 


M A V/ 

ny v 


□ v r 


UU rC 


Bit. J 


iHL 


D V 1 
DA t 1 


nmr 
UU ft 


ii d 3 I nnnn 


MAW 

ny v 


PT n 

il T D 


n n a n 
UUoc 


DJiLb 


U 1 

iHL 


PT T 
il 1 1 


D0S4 


CMdECEUU 


LES 


TV T n T Q T 


DDflfl 


ZbflBOl 


MOV 


AXiES:[BX].ABASED[DI] 


DDflB 


C41ECEDD 


LES 


BX,PTR_1 


ODflF 


Ebfi^DO 


nov 


ESMBXl.ABASEDISIJ.AX 


uD<i2 


E1010Q 


jiip 


iM 








; STATEMENT 




il: 






DDT5 


flBDbOOOO 


nov 


AXi A 




4D 


INC 


AX 


DDTA 


□TDbOOQQ 


nov 


Ai AX 



# b 



Figure 11-3 Sample Program Showing the OPTIMIZE(O) Control (continued) 
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PL/M-flb COMPILER 



EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mm:ss 

ASSEMBLY LISTING OF OBJECT CODE 



PAGE 3 



QDIE EU5FF 



5)4: 
35: 



jnp 



MODULE INFORMATION: 

CODE AREA SIZE = OOA1H 

CONSTANT AREA SIZE = ODDDH 

VARIABLE AREA SIZE = DDDbH 

MAXIMUM STACK SIZE = ODDDH 

lb LINES READ 

D PROGRAM WARNINGS 

D PROGRAM ERRORS 

DICTIONARY SUMMARY : 

4KB MEMORY USED 
OKB DISK SPACE USED 

END OF PL/M-Sb COMPILATION 



STATEMENT # 11 



STATEMENT # IE 



IblD 
DD 

214D 
OD 



Figure 11-3 Sample Program Showing the OPTIMIZE(O) Control (continued) 



OPTIMIZE(l). OPTIMIZE(l) specifies strength reduction, elimination of common 
subexpressions, short-circuit evaluation of some Boolean expressions, as well as the 
optimizations of level (0). 

Strength reduction means substituting quick operations in place of longer operations 
(e.g., shifting by 1 instead of multiplying by 2). This instruction requires less space 
and executes faster. The occurrence of identical subexpressions may also generate 
left shift instructions. 

Elimination of common subexpressions means that if an expression reappears in the 
same block, its value is re-used rather than recomputed. The compiler also recog- 
nizes commutative forms of subexpressions (e.g., A + B and B + A are seen as the 
same). Intermediate results during expression evaluation are saved in either registers 
or on the stack for later use. For example: 

A=B+C*D/3^ 
C=E+D*C/3n 

The value of C*D/3 will not be recomputed for the second statement. 
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Optimizing the evaluation of Boolean expressions uses the fact that in certain cases 
some of the terms are not needed to determine the value of the expression. For 
example, in the expression: 
( A > B AND I > J ) 

if the first term (A>B) is false, the entire expression is false, and it is not necessary 
to evaluate the second term. The use of PL/M built-in procedures does not change 
this optimization. However, if a user-function or an embedded assignment is part of 
the expression, this short evaluation is not done. For example: 

(A > B AND ( UFUN (A) > J ) ) 
is evaluated in full. 

Figure 1 1-4 illustrates the OPTIMIZE (1) level of optimization. 



PL/M-Ab COMPILER EXAMPLES_OF_0PTIMIZATIONS mm/dd/yy hh:mm:ss PAGE 1 

system-id PL/M-Ab Vx-y COMPILATION OF MODULE EXAMPLES_OF_OPTIMIZATI0NS 
OBJECT MODULE PLACED IN example-obj 

COMPILER INVOKED BY: plmAb example. src PW(7A) COMPACT CODE OPTIMIZE(l) 
NOLIST 

5 STATEMENT * 3 



0000 


ABEC 


MOV 


BPiSP 


DQDS 


FB 


STI 






il: 






0003 


AB1E0000 


nov 


BXiA 


0007 


ABSbOSOO 


MOV 


SInB 


000B 


03DE 


ADD 


BX-.SI 


0DDD 


53 


PUSH 


BX i 1 


0Q0E 


D1E3 


SHL 


BX-,1 


0010 


SF 


POP 


DI \ 1 


0011 


47 


INC 


DI 


0012 


D1E7 


SHL 


DInl 


0014 


ABA70b0O 


MOV 


AX i D[BX] 


ooia 


3BASOL-00 


CMP 


AX.D1DI] 


001C 


7503 


JB 


$ + SH 


0D1E 


E1L-D00 


JMP 


12 



Figure 11-4 Sample Program Showing the OPTIMIZE(l) Control 
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PL/M-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:min:ss PAGE 2 
ASSEMBLY LISTING OF OBJECT CODE 

i STATEMENT « 4 



0051 


C40bCE00 


LES 


BX-,PTR_1 


DOES 


B104 


MOV 


CL n 4H 


0027 


6CC7 


MOV 


DInES 


002=1 


flDBO 


MOV 


DXt AX 


002B 


D3EA 


SHR 


DX-.CL 


002D 


03FA 


ADD 


DItDX 


002F 


fllEOOFOO 


AND 


AX-iOFH 


0033 


C41bD200 


LES 


DX,PTR_2 


0037 


ACC3 


MOV 


BXnES 


003=1 


SBF2 


MOV 


SI.DX 


003B 


D3EE 


SHR 


Slid 


003D 


03DE 


ADD 


BXnSI 


003F 


61E2DF00 


AND 


DXtOFH 


0043 


3BFB 


CMP 


DI-.BX 


0045 


7502 


JNZ 


$ + 4H 


0047 


3BC2 


CMP 


AXnDX 


004=1 


7203 


JB 


$ + SH 


004B 


E=13=100 


JMP 


33 








5 STATEMENT 


004E 


□B1E0000 


MOV 


BXiA 


0052 


D1E3 


SHL 


BXil 


0054 


8=11E0000 


MOV 


A,BX 








• n STATEMENT # 


OOSfl 


flB3b0200 


MOV 


SI-.B 


OOSC 


DIEb 


SHL 


SIil 


DOSE 


D1E3 


SHL 


BXnl 


OObO 


53 


PUSH 


BX S 1 


OObl 


C1ECE0O 


LES 


BX-,PTR_1 


00b5 


2bflB00 


MOV 


AX-,ES:[BX].ABASED[SI] 


DOL-fl 


5E 


POP 


SI \ 1 


00L-=1 


21=6=100 


MOV 


ES:[BX].ABASED[SI]-,AX 








; STATEMENT 


OObC 


□B1E0400 


MOV 


BX-.C 


0070 


D1E3 


SHL 


BXil 


0072 


□B3L0200 


MOV 


SIiB 


007b 


DIEb 


SHL 


SI-.1 


007S 


C43ECE00 


LES 


DItPTR.I 


007C 


2b8B01 


MOV 


AX-,ES:[BX]-ABASED[DI] 


007F 


SBDE 


MOV 


BXnSI 


0081 


2bfl=101 


MOV 


ES:[BX]-ABASED[DI]-,AX 


00fl4 


E=10400 


JMP 


34 



Figure 11-4 Sample Program Showing the OPTIMIZE(l) Control (continued) 
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PL/M-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS 
ASSEMBLY LISTING OF OBJECT CODE 



DQA7 FFObOOOO 



DQflB E17SFF 



33: 

] 

an: 
as: 



INC 



JMP 



ai 



MODULE INFORMATION: 

CODE AREA SIZE = DOflEH 

CONSTANT AREA SIZE = DQDDH 

VARIABLE AREA SIZE = OODbH 

MAXIMUM STACK SIZE = DDDSH 

It LINES READ 

Q PROGRAM DARNINGS 

PROGRAM ERRORS 

DICTIONARY SUMMARY : 

4KB MEMORY USED 
DKB DISK SPACE USED 

END OF PL/M-Sb COMPILATION 



14ED 
DD 
214D 
SD 



mm/dd/yy hh'-mm'-ss PAGE 3 



STATEMENT » 10 



STATEMENT # 11 



STATEMENT # IE 



Figure 11-4 Sample Program Showing the OPTIMIZE(l) Control (continued) 



OPTIMIZE(2). OPTIMIZER) includes OPTIMIZE(O) and OPTIMIZE(l), plus the 
following: 

• Machine code optimizations (e.g., short jumps, moves) 

• Elimination of superfluous branches 

• Re-use of duplicate code 

• Removal of unreachable code and reversal of branch conditions 

Optimizing machine code means saving space by using shorter forms for identical 
machine instructions. This is possible because the microprocessor has multiple forms 
for some of its instructions. For example: 

MOV RESLT1-, AX=, 

/* move accumulator value to location RESLT1 */ 

can be generated using three or four bytes for PL/M-86 and PL/M-286, and using 
five or six bytes for PL/M-386. The former choice saves a byte of storage for the 
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program. Similarly, jumps that the compiler can recognize as within the same seg- 
ment or closer (within 127 bytes) permit the use of fewer byte instructions. 

Elimination of superfluous branches means optimizing consecutive or multiple 
branches into a single branch. For example: 

JZ L AB1 =i /* Jump on zero to LABI */ 

JMP L ABE i /* unconditional jump to LAB2 */ 

LABI : 

L ABB : 

will be transformed into: 

JNZ L ABE =, /* Jump on non-zero to LABE */ 

LABI: 

L ABE : 

Similarly, multiple branches like the following are eliminated: 
LABD : JMP LABI 

LABI: JMP LABE 

LABE: 

and transformed into: 
LABD : JMP LABE 

LABI: JMP LABE 

LABE: 

Reuse of duplicate code can refer to identical code at the end of two converging paths. 
In such a case, the code is inserted in only one path, and a jump to that path is inserted 
in the other path. For example: 

DECLARE A BYTE-, SPOT POINTER i 

DECLARE S BASED SPOT STRUCTURE (B BYTE-, C BYTE ) '■> 
IF A = 1 THEN 

S.C = INPUT (DF7H) AND D7FH i 
ELSE 

S.C = INPUT (DF1H) AND D7FH i 
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Before 



After 



31: 



32: 



CI1P 


Ai IH 




CMP 


An IH 


JZ 


& + SH 




JIIP 


31 


jiip 


ai 








IN 


0F7H 




IN 


DF7H 


AND 


AL-, 7FH 




jmp 


32 


nov 


BX-, SPOT 








nov 


S [BX + 1H]-, AL 








JIIP 


as 








IN 


□ FTH 


31: 


IN 


DFTH 


AND 


AL n 7FH 


32: 


AND 


AL-i 7FH 


nov 


BX i SPOT 




110V 


BX-. SPOT 


nov 


S [BX + 1H]-, AL 




110V 


S [BX + 1HML 



Reuse of duplicate code can also refer to machine instructions, immediately preced- 
ing a loop, that are identical to those ending the loop. A branch can be generated to 
reuse the code generated at the beginning of the loop. For example: 



Before 



LABO: 



ADD 
110V 

nov 

CMP 
JNZ 



AX n BX 
ANS-, AX 
ALi Dum 
AL-, DUn2 
LABI 



After 

LABD: ADD AX i BX 
nov ANS -i AX 
MOV AL n Dum 
cnp AL n DUn2 
JNZ LABI 



LABI: 



ADD 

nov 
jnp 



AX n BX 
ANS -i AX 
LABD 



jnP LABD 



LABI: 



This is safe so long as LABO is not the target of a jump instruction. The compiler 
normally handles a whole procedure at a time, and is aware of such a condition. This 
optimization cannot be safely applied to labels in the outer level of the main program 
module. This optimization will not change the program and will save code space. 

Second level optimization removes unreachable code, takes a second look at the 
generated object code, and finds areas that can never be reached due to the control 
structures created earlier. 
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For example, if the following code were generated before optimization: 



31: 



NOV 


AXn A 


RCR 


AL-i 1 


JB 


ai 


JMP 


as 


MOV 


AX n DFFFFH 


OUT Id 


□ FbH 


JMP 


as 


MOV 


AXn B 


ADD 


An AX 


JMP 


33 



33: 



then the removal of unreachable code would produce: 



MOV 


AX i A 


RCR 


AL-, 1 


JB 


31 


JMP 


32 


MOV 


AX i DFFFFH 


OUTU 


OFbH 


JMP 


32 



32: ... 
33". 



This can be further optimized by reversing the branch condition in the third instruc- 
tion and removing the unnecessary JMP @2: 

MOV AX n A 
RCR AL-, 1 
JNB 32 



31: MOV AX i DFFFFH 

OUTU OFtH 
32 : ... 

33: 



Figure 11-5 illustrates the OPTIMIZE (2) level of optimization. 
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PL/M-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mm:ss PAGE 1 

system-id PL/M-flb Vx.y COMPILATION OF MODULE EXAMPLES_OF_OPTIMIZATIONS 
OBJECT MODULE PLACED IN example-obj 

COMPILER INVOKED BY: plmflb example-src Pli)(7fl) COMPACT CODE OPTIMIZED) 
NOLIST 



i STATEMENT * 3 



n n n n 


n d c r 

flBEC 


M A U 

nOv 


BP i SP 


0002 


FB 


STI 






81: 






0003 


ABIEOOOO 


MOV 


BX-,A 


0007 


A10200 


MOV 


AX-.B 


OOOA 


03DA 


ADD 


BXt AX 


OOOC 


S3 


PUSH 


BX i 1 


OOOD 


D1E3 


SHL 


BX-,1 


OOOF 


SE 


POP 


si ; i 


001Q 


4b 


INC 


SI 


0011 


DIEb 


SHL 


SI-,1 


0013 


ABflFObOO 


MOV 


CX-,D[BX] 


0017 


SBflCObOO 


CMP 


CX-,D[SI] 


001B 


73bb 


JNB 


81 


001D 


C41bCE00 


LES 


BX-,PTR_1 


00S1 


B104 


MOV 


CL-,4H 


0053 


flCCb 


MOV 


SI-.ES 


0055 


fiBFA 


MOV 


DItDX 


0057 


D3EF 


SHR 


DI-.CL 


0051 


D3F7 


ADD 


SIiBI 


005B 


fllESOFOO 


AND 


DXtOFH 


0Q5F 


C41ED500 


LES 


BXtPTR_5 


0033 


6CC7 


MOV 


di-.es 


003S 


ABC3 


MOV 


AX-iBX 


0037 


D3E6 


SHR 


AXnCL 


0031 


03Ffl 


ADD 


DI-.AX 


003B 


fllESOFOO 


AND 


BXiOFH 


DD3F 


3BF7 


CMP 


SI^DI 


oom 


7S05 


JNZ 


$+4H 


0043 


3BD3 


CMP 


DXtBX 


004S 


733b 


JNB 


33 


0047 


A1000D 


MOV 


AXnA 


004A 


DIED 


SHL 


AX-,1 


004C 


A30000 


MOV 


A,AX 


004F 


BB1E0500 


MOV 


BX-iB 


DO S3 


D1E3 


SHL 


BX-,1 



STATEMENT * b 
STATEMENT # 7 



Figure 11-5 Sample Program Showing the OPTIMIZER) Control 
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PL/n-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mm:ss PAGE 2 

ASSEMBLY LISTING OF OBJECT CODE 



DOSS DIED 

0057 C43bCE00 

DOSB SbflBOfl 

OOSE ABDfl 

OObO 2^06 

0Db3 6B1E0400 

00b7 D1E3 

OObT flB3b0200 

OObD DIEb 

oobF c4seceoo 

0073 2bflB01 

007L- fiBDE 

007fl SbflTDl 

007B EBflb 

33: 

007D FFObOOOO 

OOfll EBflO 

32: 



MODULE INFORMATION: 

CODE AREA SIZE = 00A3H 

CONSTANT AREA SIZE = OOOOH 

VARIABLE AREA SIZE = ODDbH 

MAXIMUM STACK SIZE = 0002H 

It LINES READ 

PROGRAM DARNINGS 

PROGRAM ERRORS 



SHL AXil 

LES SI-,PTR_1 

MOV CXtESMBXJ.ABASEDISI] 

MOV BXiAX 

MOV ES:[BX].ABASED[SI]-,CX 

\ STATEMENT # I 

MOV BXiC 

SHL BX-il 

MOV SI-.B 

SHL SI-,1 

LES DIiPTR_l 

MOV AX-,ES:[BX].ABASED[DI] 

MOV BX-iSI 

MOV ES:[BX].ABASED[DI]iAX 
JMP 31 

'< STATEMENT # 10 

INC A 

i STATEMENT * 11 

JMP 31 

* STATEMENT * 12 



131D 
OD 

214D 
2D 



DICTIONARY SUMMARY: 



4KB MEMORY USED 
DKB DISK SPACE USED 



END OF PL/M-flb COMPILATION 



Figure 11-5 Sample Program Showing the OPTIMIZER) Control (continued) 
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OPTIMIZE (3). OPTIMIZER) includes all of the preceding optimizations. It also 
optimizes indeterminate storage operations (e.g., those using based variables or 
variables declared with the AT attribute). 



NOTE 

The assumption validating this new optimization is that based variables (or AT 
variables) do not overlay other user-declared variables. 

On this optimization level, all Boolean expressions are short-circuited except those 
containing embedded assignments. (For a description of how this optimization oc- 
curs, see OPTIMIZE(l).) 

The benefits of this optimization level include more efficient use of code space only if 
needed values are not overlaid. 



Caution in variable-declaration and usage is essential. For example, the sequence: 

DECLARE J) WORD i 

DECLARE THETA (IT) AT (SI)", 
DECLARE A BASED J (ID) i 
STRUCTURE (Fl BYTE-, F2 WORD); 

J = .Ii 



A (I) -Fl = 7i 
A(I) -F2 = ITi 
THETA ( I ) = 31i 



violates this caution because it causes the values being used as pointers and subscripts 
to be overlaid. The compiler normally takes steps to avoid the difficulties implied 
here. But, in OPTIMIZER), these steps are omitted due to the implicit requirement 
that such situations must not be present at this level of optimization. 

Figure 1 1-6 illustrates the OPTIMIZE (3) level of optimization. 
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PL/M-flb COMPILER EXAMPLES_OF_OPTiniZATIONS 



mm/dd/yy hh'-mm'-ss PAGE 1 



system-id PL/M-flk Vx-y COMPILATION OF MODULE EXAMPLES_0F_0PTIMIZATIONS 
OBJECT MODULE PLACED IN example. obj 

COMPILER INVOKED BY: plmflb example. src PU(7fl) COMPACT CODE OPTIMIZED) 
NOLIST 

i STATEMENT # 3 



0000 


8BEC 


MOV 


BPiSP 




0005 


FB 

31: 


STI 






0003 


6B1E0000 


MOV 


BX-iA 




0007 


A10500 


MOV 


AX-.1 




000A 


03Dfl 


ADD 


BXtAX 




OOOC 


S3 


PUSH 


BX i 1 




000D 


D1E3 


SHL 


BX-,1 




000F 


SE 


POP 


SI n 1 




0010 


4b 


INC 


SI 




0011 


D1EL- 


SHL 


SIil 




0013 


flBflFObDD 


MOV 


CX-,D[BX] 




0017 


SBflCObOO 


CMP 


CX,D[SI] 




001B 


733B 


JNB 


13 


STATEMENT 


001D 


C41ECE00 


LES 


BX-,PTR_1 




0051 


flCCb 


MOV 


SI-.ES 




0053 


3B3bD400 


CMP 


SI-,PTR_5+5H 


0057 


7S04 


JNZ 


$+bH 




005=1 


3B1ED500 


CMP 


BXtPTR_5 




005D 


7S53 


JNZ 


33 


STATEMENT 


005F 


AB3E000D 


MOV 


DI.A 




0033 


DIE? 


SHL 






0035 


fl13E0000 


MOV 


AvW 


STATEMENT 


003T 


D1E0 


SHL 


AX„1 




003B 


D1E7 


SHL 


DI-,1 




003D 


lb 


XCHG 


AX-.SI 




003E 


SbBBOS 


MOV 


CXnES:[BX]. 


ABASED[SI] 


0041 


SbfllOl 


MOV 


ES:[BX].ABASED[DI]-,CX 










STATEMENT 


0044 


SB3E0400 


MOV 


DI-.C 




004A 


D1E7 


SHL 


DI-,1 




004A 


5bAB01 


MOV 


CX-,ES:[BX]. 


ABASED[DI] 


004D 


EbflTDfl 


MOV 


ES:[BX].ABASED[SI]-,CX 


0050 


EBB1 


JMP 


31 





Figure 11-6 Sample Program Showing the OPTIMIZE(3) Control 
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PL/M-flb COMPILER EXAMPLES_OF_OPTIMIZATIONS mm/dd/yy hh:mm:ss PAGE 5 

ASSEMBLY LISTING OF OBJECT CODE 



33: 



0052 FFObOOOO 
005b EBAB 



INC A 
JMP 31 



32: 



MODULE INFORMATION: 

CODE AREA SIZE 
CONSTANT AREA SIZE 
VARIABLE AREA SIZE 
MAXIMUM STACK SIZE 
lb LINES READ 
PROGRAM WARNINGS 
PROGRAM ERRORS 



0056H 
OOOOH 
OODbH 
0002H 



flfiD 
OD 
214D 
2D 



\ STATEMENT « 10 
; STATEMENT # 11 
5 STATEMENT # 12 



DICTIONARY SUMMARY: 

4KB MEMORY USED 
OKB DISK SPACE USED 

END OF PL/M-flb COMPILATION 



Figure 11-6 Sample Program Showing the OPTIMIZER) Control (continued) 
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11.2.14 OVERFLOW/NOOVERFLOW 



Form 



OVERFLOW 
NOOVERFLOW 



Default NOOVERFLOW 



Type 



General 



Discussion 



These controls specify whether overflow is to be detected in performing signed arith- 
metic. If the NOOVERFLOW control is specified, no overflow detection is imple- 
mented in the compiled module and the results of overflow in signed arithmetic are 
undefined. If the OVERFLOW control is specified, overflow in signed arithmetic 
results in a nonmaskable interrupt 4, and it is the programmer's responsibility to 
provide an interrupt procedure to handle the interrupt. Failure to provide such a 
procedure may result in unpredictable program behavior when overflow occurs. 

If this control is nested within a program statement, overflow detection will begin 
when the next complete statement is evaluated. 

Note that the use of the OVERFLOW control results in some expansion of the object 
code. 

Specific to the 80386 microprocessor, in-line checking code is inserted for detecting 
machine overflow (32-bit arithmetic overflow) on signed expressions, and value over- 
flow on assignments to SHORTINT or CHARINT variables. 

To save code space and execution time, avoid using SHORTINT and CHARINT 
when compiling with the OVERFLOW control. 



11.2.15 PAGELENGTH 



Form 



PAGELENGTH(n) 



Default PAGELENGTH(60) 



Type 



Primary 
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Discussion 

Pagelength is a non-zero, unsigned number specifying the maximum number of lines 
to be printed per page of listing output. This number is taken to include the page 
headings appearing on the page. 

The minimum value for length is 5 ; the maximum value is 255 . 

11.2.16 PAGEWIDTH 

Form PAGEWIDTH(n) 
Default PAGEWIDTH(120) 
Type Primary 

Discussion 

Pagewidth is a non-zero, unsigned number specifying the maximum line width, in 
characters, to be used for listing output. The minimum value for width is 60; the 
maximum value is 132. 

11.2.17 PAGING/NOPAGING 

Form PAGING 

NOPAGING 

Default PAGING 

Type Primary 

Discussion 

The PAGING control specifies that the listed output is to be formatted onto pages. 
Each page carries a heading identifying the compiler and a page number, and possi- 
bly a user specified title. 

The NOPAGING control specifies that page ejecting, page heading, and page num- 
bering are not to be performed. Thus, the listing appears on one long page as would 
be suitable for a slow serial output device. If NOPAGING is specified, a page eject is 
not generated if an EJECT control is encountered. 
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11.2.18 PRINT/NOPRINT 



Form 



PRINT(paf/7name) 
NOPRINT 



Default 



PR\NT{sourcefilename.LST) 



Type 



Primary 



Discussion 



The PRINT control specifies that printed output is to be produced. Pathname is a 
standard host operating system pathname that specifies the file to receive the printed 
output. Any output-type device, including a disk file, can also be given. If the control 
is absent, or if a PRINT control appears without a pathname, printed output is sent to 
a file that has the same name as the source input file but with the extension .LST. 

The NOPRINT control specifies that no printed output is to be produced, even if 
implied by other listing controls such as LIST and CODE. 



Default RAM (Except in the LARGE model for PL/M-86 and PL/M-286, in which 



Type Primary 
Discussion 

Specific to PL/M-86, the RAM setting directs the object-module placement of all 
constants, both user-defined and compiler-generated. The default setting places the 
CONSTANT section within the DATA segment in all segmentation models (sizes) 
except LARGE. In the LARGE model, with the ROM setting, constants are placed in 
the CODE segment. 

For PL/M-286 and PL/M-386, the RAM setting places the CONSTANT section 
within the DATA segment in all segmentation models (sizes). 

For all of the microprocessors, the ROM setting places constants in the CODE seg- 
ment. Under this setting, the INITIAL attribute on a variable produces a warning 
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11.2.19 RAM/ROM 



Form 



RAM 
ROM 



case ROM is the default.) 



message. The dot operator is not advised for variable references under the ROM 
option because constants and variables will be relative to different segment registers. 
If SMALL is specified with the ROM control, then PL/M-86 and PL/M-286 pointers 
will be four bytes instead of two and PL/M-386 pointers will be six bytes instead of 
four. (See also Appendix F.) 

If the keyword DATA is used in a PUBLIC declaration when compiling with the 
ROM control, DATA must also be used in the EXTERNAL declaration of program 
modules that reference it. However, no value list is then permitted because the data is 
defined elsewhere. 

11.2.20 SAVE/RESTORE 

Form SAVE 

RESTORE 

Default None 

Type General 

Discussion 

With these controls the settings of certain general controls can be saved on a stack 
and then restored. The main usage of these controls is saving the controls before an 
included file and restoring them after inclusion of that file is complete. The controls 
whose settings are saved and restored are: 

CODE/NOCODE 
COND/NOCOND 
LEFTMARGIN 
LIST/NOLIST 

OVERFLOW/NOOVERFLOW 

The SAVE control saves all of these settings on a stack. The maximum capacity of 
this stack corresponds to the maximum nesting depth for the INCLUDE control (the 
maximum nesting depth is given in Appendix B). 

The RESTORE control restores the most recently saved set of control settings from 
the stack. 
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11.2.21 SET/RESET 



These are general controls. The SET control has the following general form: 

Form SET(switch_assignment_list) 

Where: 

switch_assignment_list consists of one or more switch assignments separated 

by commas. 

A switch assignment has the form: 
switch 

or 

switch = value 
Where: 

switch is a name which is formed according to the PL/M rules for identifiers. 

Note that a switch name exists only at the compiler control level, and 
therefore a switch can have the same name as an identifier in the pro- 
gram; no conflict is possible. Note however that no PL/M reserved 
word other than a predefined switch can be used as a switch name. 

value is a whole-number constant in the range to 255. This value is as- 
signed to the switch. If the value and the equal sign ( = ) are omitted 
from the switch assignment, the default value OFFH (true) is assigned 
to a switch. 

The following is an example of a SET control line: 
$SET( TEST -i ITERATION = 3) 

This example sets the switch TEST to true (OFFH) and the switch ITERATION to 3. 
Switches do not need to be declared. 

Figure 11-1 and 11-2 (see Section 11.1.10) are examples of a program that was 
compiled using the SET control. 

The RESET control has the form: 
RESET (switch Jist) 

Where: 

switch_Jist consists of one or more switch names that have already occurred in 
SET controls. 
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Each switch in the switch list is set to false (0). 
Default None 
Type General 

1 1 .2.22 SMALL/COMPACT/MEDIUM/LARGE 

The following sections describe the SMALL, COMPACT, MEDIUM, and LARGE 
controls (also called the segmentation controls). 

11.2.22.1 SMALL 

Form SMALL 

Default SMALL for PL/M-86 and PL/M-386 
LARGE PL/M-286 

Type Primary 
Discussion 

PL/M-86 — 

When modules compiled with the SMALL control are linked, the code sections from 
all modules are combined and are allocated space within one segment. The segment 
address for this segment is kept in the CS register. The constant, data, stack, and 
memory sections from all modules are allocated space within a second segment. The 
segment address for this second segment is kept in the DS register, with an identical 
copy in the SS register. 

Therefore, the SMALL control may be used only if the total size of all code sections 
does not exceed 64K bytes, and the total size of all constant, data, stack, and memory 
sections does not exceed 64K bytes. 

Because there is only one segment for code, the segment address for this segment (CS 
register) is never updated during program execution. Likewise, since there is only 
one segment for constants, data, stack, and memory sections, the segment address for 
this segment (DS and SS registers) is never updated (except when an interrupt occurs, 
as explained in Appendix G). Therefore, when any location is referenced, only a 16- 
bit offset is calculated and then used in conjunction with the appropriate segment 
address. POINTER values are therefore 16-bit values in the SMALL case, and this 
leads to the following restrictions. 
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— PL/M-86 

(continued) 

1. POINTER variables cannot be initialized with, or assigned, whole-number con- I 
stants. For example: 

DECLARE RR POINTER INITIAL (2277); 

/* invalid under SHALL */ 

DECLARE SS POINTER ; 

SS = 100 =i /* invalid under SHALL */ 

2. The @ operator must not be used with a variable that was located at an absolute 
address specified by a whole-number constant. For example: 

DECLARE JO BYTE AT (10D)-, P0 POINTERS 

P0 = 3J0; /* invalid under SHALL */ 

This restriction does not apply if the absolute address in the declaration is created 
by the @ operator with a variable, as in: 

DECLARE LIKE BYTE-, N AGE POINTER; 
DECLARE SKI BYTE AT OUKE); 

N AGE = aSKl; /* valid */ 

3. The PUBLIC attribute must not be used with a variable located at an absolute 
address specified by a whole-number constant. As in restriction 2, this does not 
apply when @ is used: 

DECLARE SHOHEN BYTE PUBLIC AT ( 100 ) n /* invalid */ 

DECLARE IKYO BYTE; 

DECLARE SANKYO BYTE PUBLIC AT OIKY0); /* valid */ 

This restriction arises because external variables are assumed to be in the DATA 
segment. 

4. Restrictions 1 and 2 apply also to WORD variables when used as offset pointers 
and to the use of the dot operator. 

5. The @ and dot operators cannot be used with variables based on SELECTOR. 
For example: 

DECLARE SEL SELECTOR ; 
DECLARE R BASED SEL BYTE; 
DECLARE P0 POINTER ; 

P0 = 3R /* invalid under SHALL */ 

6. If the built-in function SELECTOR$OF is used, it will always return the value 

of the DS register. If BUILD$PTR is used, it will ignore the SELECTOR I 
expression (see Section 9.8). end 

— PL/M-86 
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Modules compiled with the SMALL control have three sections: code, data, and 
stack (see the OBJECT control). When these modules are linked, similar sections 
from each module are combined to form two segments: code and data. The maximum 
size of each segment for the 80286 microprocessor is 64K bytes. For the 80386 
microprocessor, the maximum size of each segment is 4G bytes. 

In the default SMALL case (RAM), the code sections from all modules are allocated 
space within the code segment, which is addressed relative to the CS register. Con- 
stants are combined with all the data and stack sections in the data segment. For the 
80286 microprocessor, this segment is addressed relative to the DS register, with an 
identical copy in the SS register. For the 80386 microprocessor, this segment is ad- 
dressed relative to the DS register, with an identical copy in the SS and ES registers. 
Specific to the 80386 microprocessor, none of the segment registers are changed 
during the course of program execution except ES, which is used to perform string 
operations, and FS and GS, which are used to address data exported by another 
subsystem. (Subsystems are described in Chapter 13.) 

Therefore, the SMALL control can be used only if the total size of all code sections 
does not exceed 64K bytes for the 80286 microprocessor and 4G bytes for the 80386 
microprocessor. Additionally, the total size of the constants plus all data and stack 
sections does not exceed the previously stated limits. 

If the ROM control is used, the constants from all the modules are placed with the 
code in the code segment. The data segment then contains only the data and stack 
sections from all the modules. 

Because only one code segment exists, its segment selector (the CS register) is never 
updated during program execution. (However, an interrupt will update the CS regis- 
ter.) Likewise, when RAM is used, only one segment exists for all constant, data, 
and stack sections. The segments' selectors (the DS and SS registers) are never up- 
dated (except when an interrupt occurs, as explained in Appendix G). Therefore, 
when any location is referenced, only a 16-bit offset for the 80286 microprocessor 
and a 32-bit offset for the 80386 microprocessor is calculated and used in conjunction 
with the appropriate segment selector. POINTER values in the SMALL (RAM) case 
are 16-bit values for the 80286 microprocessor and 32-bit values for the 80386 
microprocessor. 



Compiler Controls 



PL/M-286/386 

(continued) 



The following restrictions must be observed: 



1 . Do not use the @ and dot operations with variables based on SELECTOR. For 
example: 

DECLARE SEL SELECTORS 
DECLARE R BASED SEL BYTE i 
DECLARE PO POINTER; 

PO = 3R=, /* invalid under SHALL RAM */ 

2. Do not use the built-in function BUILD$PTR (see Section 9.6). 

end 

— PL/M-286/386 



PL/M-86/286 



PL/M-80 Compatibility 



The SMALL control is the most likely choice when recompiling a program written in 
PL/M-80. The compiler produces error messages to flag violations of any of the 
restrictions or to flag the use of the new reserved keywords (DWORD, INTEGER, 
REAL, POINTER, SELECTOR, and CAUSE$INTERRUPT) as programmer- 
defined identifiers. Otherwise, complete upwards compatibility is provided by 
PL/M-86 and PL/M-286. 

end 

— PL/M-86/286 



NOTE 

Care must be used with the dot operator under conditions other than SMALL 
(RAM). 

11.2.22.2 COMPACT 

Form COMPACT 

Default SMALL for PL/M-86 and PL/M-386 
LARGE for PL/M-286 

Type Primary 
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Discussion 

PL/M-86 — 

A program compiled with the COMPACT control has four sections: code, data, 
stack, and memory. Each of these is the result of combining the same-type sections 
from all modules, and each has a maximum size of 64K bytes. The constant sections 
from all modules are grouped with the data segment unless the ROM control is used, 
which causes all constant sections to be merged into the CODE segment instead. 
Since the code, data, and stack segments are fully defined by the time the program is 
loaded, the segment base addresses in the CS and SS registers are never changed. 
(The DS register may change when an interrupt occurs, as explained in Appendix F.) 

All code and a few prologue constants are addressed relative to CS. All data except 
absolute data (declared with the AT constant attribute) are addressed relative to DS. 
The stack is addressed relative to SS. ES is not initialized and can change during 
execution. References to any location require only a 16-bit offset address against 
these segment base addresses. 

Do not declare PUBLIC variables AT an absolute location, as in: 
DECLARE ANVIL BYTE PUBLIC AT ( ) ^ 

This restriction does not apply when the location within the AT attribute is formed 
with the @ operator. Therefore, DECLARE ANVIL BYTE PUBLIC AT (@HAMR) 
is valid. However, do not use the phrases @ MEMORY and MEMORY to define a 
PUBLIC variable. 

86 — 

286/386 — 

Modules compiled with the COMPACT control have three sections: code, data, and 
stack (see the OBJECT control). When these modules are linked, similar sections 
from each module are combined to form three segments: code, data, and stack. The 
maximum size of each segment is 64K bytes for the 80286 microprocessor and 4G 
bytes for the 80386 microprocessor. 

In the default COMPACT case (RAM), the code sections from all modules are allo- 
cated space within the code segment, which is addressed relative to the CS register. 
Constants and all data sections are combined in the data segment, which is addressed 
relative to the DS register and, for the 80386 microprocessor, an identical copy is 
stored in the ES register. The stack is addressed relative to SS. Specific to the 80386 
microprocessor, none of the segment registers are changed, except ES, which is used 
to perform string operations, as well as FS and GS, which are used to address data 
exported by another subsystem. 
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— PL/M-286/386 

(continued) 

If the ROM control is used, the constants from all the modules are placed with the I 
code in the code segment. The data segment then contains only the data sections from 
all the modules. 



Since the code, data, and stack segments are fully defined by the time the program is 
loaded, the segment selectors in the CS and SS registers are never changed. 

For the 80286 microprocessor, ES is not initialized and can change during execution. 
References to any location require only a 16-bit offset against these segment 
selectors. 



Specific to the 80386 microprocessor, all six segment registers are initialized by the 
loader, with ES, FS, and GS initialized to DS. The DS and ES registers are also saved 
and reinitialized in each interrupt procedure prologue and epilogue to enable distinct 
interrupt environments. The FS and GS registers are volatile after initialization. Ref- 
erences to any location require only a 32-bit offset against these segment selectors. 

end 

— PL/M-286/386 



Observe the following restrictions when using COMPACT. 

1 . When an exported procedure is indirectly activated, a POINTER variable must 
be used in the CALL statement. For example: 

$COMPACT(SUBSYS HAS MODI-, M0D5-, M0D3; EXPORTS PR0O 
MOD : DO 

DECLARE P POINTERi U WORD i 

PROC: PROCEDURE PUBLIC; 



END PROC; 

P = 3PR0C; CALL P; /* POINTER must be used */ 

lil = -PR0C; CALL bin /* not allowed */ 

END MODI; 
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PL/M-86/286 — 

2. For the 8086 and 80286 microprocessors, when a procedure that is not exported 
is indirectly activated, a WORD variable must be used. Note that WORD vari- 
ables do not range over the entire microprocessor address space, but are re- 
stricted to offsets within the current code segment. For example: 

DECLARE P POINTER -> U WORD i 

LPROC: PROCEDURE i /* local */ 



END LPROC; 

P = 3LPR0C; CALL Pi 
I Id = -LPR0C; CALL U; 

end 

PL/M-86/286 — 
PL/M-386 — 



/* not allowed */ 
/* WORD must be used */ 



For the 80386 microprocessor, when a procedure that is not exported is indi- 
rectly activated, an OFFSET variable must be used. Note that OFFSET variables 
do not range over the entire microprocessor address space, but are restricted to 
offsets within the current code segment. For example: 

DECLARE P POINTER-, OFFSET ; 

LPROC: PROCEDURE; /* local */ 



end 

PL/M-386 



END LPROCi 

P = 3LPR0C; CALL Pi /* not allowed */ 

= -LPROCi CALL 0; /* OFFSET must be used */ 



11.2.22.3 MEDIUM 

Form MEDIUM 

Default SMALL for PL/M-86 and PL/M-386 
LARGE for PL/M-286 

Type Primary 
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Discussion 

— PL/M-86/286 

For PL/M-86, modules compiled with the MEDIUM control have four sections: 
constant, data, stack, and memory. For PL/M-286, modules compiled with the 
MEDIUM control have three sections: code, data, and stack (see the OBJECT con- 
trol). In the default MEDIUM case (RAM), the code section from each module 
makes up its own code segment. Thus, the total code space for each program may 
exceed 64K bytes, though the maximum size of any one code segment is limited to 
64K bytes. At any moment during program execution, one code segment is the cur- 
rent segment, and its segment selector is kept in the CS register. This selector is 
updated whenever a PUBLIC or EXTERNAL procedure is activated, because a new 
code segment may be created as the result of a procedure activation. 

All sections for all of the modules are combined in the data segment, which is ad- 
dressed relative to the DS register (with an identical copy in the SS register) and is 
never changed (except when an interrupt occurs, as explained in Appendix G). 

Specific to PL/M-286, if the ROM control is used, the constant section from each 
module is placed with the code in its code segment. The data segment then contains 
only the data and stack sections from all the modules. 

Specific to PL/M-86, with the MEDIUM control, a POINTER value is a four-byte 
quantity containing a segment address and an offset. 

Because the code segment selector may change during program execution, the fol- 
lowing restrictions must be observed. 

1. When a PUBLIC (or EXTERNAL, for PL/M-86) procedure is indirectly acti- 
vated, a POINTER variable must be used in the CALL statement. For example: 

DECLARE P POINTER, U WORD; 
PROC: PROCEDURE PUBLIC i 



END PROCi 

P = SPROCi CALL Pi /* POINTER must be used for an indirect call */ 
bl = -PROCi CALL lili /* not allowed */ 
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PL/M-86/286 — 

(continued) 

2. When a procedure that is not PUBLIC or EXTERNAL is indirectly activated, a 
WORD variable must be used. This is consistent with PL/M-80, but is not rec- 
ommended for PL/M-86 and PL/M-286 programs because WORD variables do 
not range over the entire microprocessor address space. The WORD variables 
are restricted to offsets within the current code segment. For example: 

DECLARE P POINTER-, lii UORDi 

LPROCi PROCEDURE i /* local */ 



END LPROO 

P = BLPROCi CALL Pi /* invalid */ 

lii = -LPROCi CALL Ui /* valid-, however */ 

/* not recommended */ 

3. Specific to the 8086 microprocessor, a variable that is absolutely located (by 
using the AT attribute with a numeric constant) cannot have the PUBLIC attri- 

Ibute. The following example is invalid in PL/M-86: 
DECLARE B BYTE PUBLIC AT ( ) 'i 

end 

PL/M-86/286 — 

For PL/M-386, the MEDIUM control is provided for PL/M-86 and PL/M-286 com- 
patibility. The MEDIUM control is interpreted exactly like the SMALL control. For 
more information, refer to the SMALL control entry in this chapter (Section 
11.2.22.1). 



11.2.22.4 LARGE 



Form LARGE 



Default SMALL for PL/M-86 and PL/M-386 
LARGE for PL/M-286 



Type Primary 
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— PL/M-86/286 

For PL/M-86, a module compiled with the LARGE control has four sections: code 
(with constants unless RAM is specified; see Section 1 1 .2. 19), data, stack, and mem- 
ory. For PL/M-286, a module compiled with the LARGE control has three sections: 
code (with constants if the ROM control is used), data (with constants if the RAM 
control is used), and stack. 

For both the 8086 and the 80286 microprocessors, each section has a separate seg- 
ment. Thus, the total space required for each section may exceed 64K, but the total 
size for each section from any one module is limited to 64K. 

At any moment during program execution, one code segment and one data segment 
are current. Code and data segments are paired, so that the current code and data 
segments are always from the same module. The compiler implements this pairing by 
placing the segment selector from the data segment in a reserved location in the code 
section. During program execution, the segment selectors for the current code and 
data segments are kept in the CS and DS registers, respectively, and are updated 
whenever a PUBLIC or EXTERNAL procedure is activated, because this may in- 
volve new code and data segments. 

The stack segment selector is kept in the SS register. Since the code segment selector 
may change during program execution, the following restrictions must be observed. 

1 . When a PUBLIC or EXTERNAL procedure is indirectly activated, a POINTER 
variable must be used in the CALL statement. For example: 

DECLARE P POINTER n W WORD i 
PROC: PROCEDURE PUBLIC; 



END PROC; 

P = aPROCi CALL Pi /* POINTER must be used */ 

W = -PROCi CALL U; /* not allowed */ 
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PL/M-86/286 — 

(continued) 

12. When a procedure that is not PUBLIC or EXTERNAL is indirectly activated, a 
WORD variable must be used. This is consistent with PL/M-80, but is not rec- 
ommended for PL/M-86 and PL/M-286 because WORD variables do not range 
over the entire microprocessor address space. WORD variables are restricted to 
offsets within the current code segment. For example: 
DECLARE P POINTER-, W WORD"-, 

LPROC: PROCEDURES /* local */ 



END LPROC:, 

P = 9LPR0C--, CALL P = 

U = ■ LPROC i CALL W- 



/* not allowed */ 
/* WORD must be used */ 



end 

PL/M-86/286 



For PL/M-386, the LARGE control is provided for PL/M-86 and PL/M-286 compat- 
ibility. The LARGE control is interpreted exactly like the COMPACT control in most 
cases. For more information, refer to the COMPACT control entry in this chapter 
(Section 11.2.22.2). When the LARGE control is used in a PL/M-386 subsystem 
definition, it behaves differently from the COMPACT control. For more information 
about subsystems, see Chapter 13. 

11.2.23 SUBTITLE 

Form SUBTITLE("sujbf/f/e") 
Default No subtitle 
Type General 

Discussion 

The subtitle character sequence (truncated on the right to fit, if necessary) is printed 
on the subtitle line of each page of listed output. Note that a subtitle specified on the 
invocation line must be enclosed in quotation marks. 

The maximum length for subtitle is 60 characters, but a narrow pagewidth may re- 
strict this number. 
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When a SUBTITLE control appears before the first noncontrol line in the source file, 
it causes the specified subtitle to appear on the first page and all subsequent pages 
until another SUBTITLE control appears. 

A subsequent SUBTITLE control causes a page eject, and the new subtitle appears on 
the next page and all subsequent pages until the next SUBTITLE control. 

11.2.24 SYMBOLS/NOSYMBOLS 

Form SYMBOLS 

NOSYMBOLS 

Default NOSYMBOLS 

Type Primary 

Discussion 

The SYMBOLS control specifies that a listing of all identifiers in the PL/M source 
program and their attributes is to be produced in the listing file. 

The NOSYMBOLS control suppresses such a listing. 

Note that the SYMBOLS control cannot override a NOPRINT control. 



11.2.25 TITLE 

Form TITLE("f/f/e") 
Default TITLE ( " modulename " ) 
Type Primary 

Discussion 

The title character sequence, truncated on the right to fit, if necessary, is placed on 
the title line of each page of listing output. Note that the character sequence for a title 
must be enclosed in quotation marks when entered on the invocation line. 

The maximum length for title is 60 characters, but a narrow pagewidth may restrict 
this number. 
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11.2.26 TYPE/NOTYPE 



Form TYPE 

NOTYPE 

Default TYPE 

Type Primary 

Discussion 

The TYPE control specifies that the object module is to contain information on the 
variable types output in symbol records. TYPE records provide a mechanism for 
promoting type compatibility between subprograms. This information may be used 
later for type checking when the program modules are combined, or by a debugger. 

The NOTYPE control specifies that such type definitions are not to be placed in the 
object module. 

PL/M-386 

11.2.27 WORD32/WORD16 

Form WORD32 
WORD16 

Default WORD32 

Type Primary 

Discussion 

The WORD32/WORD16 control determines how the compiler interprets the un- 
signed binary number and signed integer scalar types (as well as the built-ins that 
specify these data types) in the code being compiled. 

When compiling PL/M-286, PL/M-86, or PL/M-80 source code with the PL/M-386 
compiler, there are several points to consider before choosing WORD32 or 
WORD16. See Section 3.7 for a discussion of these points. 



11-60 



Compiler Controls 



— PL/M-386 

(continued) 

Table 11-2 lists the data types as interpreted by the compiler under WORD32 and \ 
WORD16. The WORD16 control does not mean creating PL/M-286 code, but rather 
that PL/M-386 data types are mapped to the equivalent PL/M-286 data type. 



Table 11-2 WORD32/WORD16 Data Type Mapping 



WORD32 


WORD16 




(native) 


(mapping) 


Number of Bits 


Unsigned Binary Number Data Types 


BYTE 


BYTE, HWORD 


8 


HWORD 


WORD 


16 


WORD 


DWORD 


32 


DWORD, QWORD 


QWORD 


64 


Signed Integer Data Types 


CHARINT 


SHORTINT, CHARINT 


8 


SHORTINT 


INTEGER 


16 


INTEGER, LONGINT 


LONGINT 


32 



Note that all built-ins that specify data types are different for WORD 16. Table 11-3 
lists the WORD32/WORD16 mapping for these built-ins. In PL/M-386, WORD16 
keywords are mapped to the equivalent WORD32 keyword. 
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PL/M-386 

(continued) 



Table 11-3 WORD32/WORD16 Built-in Mapping 



WORD32 


WORD16 


(type conversions) 


(type conversions) 


BYTE 


BYTE, HWORD 


HWORD 


WORD 


WORD 


DWORD 


DWORD, QWORD 


QWORD 


CHARINT 


SHORTINT, CHARINT 


SHORTINT 


INTEGER 


INTEGER 


LONGINT 


BLOCKINPUT 


BLOCKINPUT 


BLOCKOUTPUT 


BLOCKOUTPUT 


MOVB 


MOVB, MOVHW 


MOVRB 


MOVRB, MOVRHW 


FINDB 


FINDB, FINDHW 


FINDRB 


FINDRB, FINDRHW 


INPUT 


INPUT, INHWORD 


OUTPUT 


OUTPUT, OUTHWORD 


SKIPB 


SKIPB, SKIPHW 


SKIPRB 


SKIPRB, SKIPRWH 


CMPB 


CMPB, CMPHW 


SETB 


SETB, SETHW 


BLOCKINHWORD 


BLOCKINWORD 


BLOCKOUTHWORD 


BLOCKOUTWORD 


MOVHW 


MOVW 


MOVRHW 


MOVRW 


FINDHW 


FINDW 


FINDRHW 


FINDRW 


INHWORD 


INWORD 


OUTHWORD 


OUTWORD 


SKIPHW 


SKIPW 


SKIPRHW 


SKIPRW 


CMPHW 


CMPW 


SETHW 


SETW 
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(continued) 



Table 11-3 WORD32/WORD16 Built-in Mapping 
(continued) 



WORD32 


WORD16 


(type conversions) 


(type conversions) 


BLOCKINWORD 


BLOCKINDWORD 


BLOCKOUTWORD 


BLOCKOUTDWORD 


MOVW 


MOVD 


MOVRW 


MOVRD 


FINDW 


FINDD 


FINDRW 


FINDRD 


INWORD 


IN DWORD 


OUTWORD 


OUTDWORD 


SKIPW 


SKIPD 


SKIPRW 


SKIPRD 


CMPW 


CMPD 


SETW 


SETD 



end 

PL/M-386 



11.2.28 XREF/NOXREF 

Form XREF 

NOXREF 

Default NOXREF 

Type Primary 

Discussion 

The XREF control specifies that a cross-reference listing of source program identifi- 
ers is to be produced in the listing file. 

The NOXREF control suppresses the cross-reference listing. 

Note that the XREF control cannot override a NOPRINT control. 
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11.3 Program Listing 



1 1 .3.1 Sample Program Listing 

During the compilation process, a listing of the source input is produced. Each page 
of the listing carries a numbered page-header that identifies the compiler, prints a 
time and date as designated by the host operating system, and optionally gives a title 
and a subtitle, and/or a date (see Figure 11-7). 

The first part of the listing contains a summary of the compilation, beginning with the 
compiler identification and the name of the source module being compiled. The next 
line names the file receiving the object code. The next line contains the command 
used to invoke the compiler. The listing of the program itself is shown in Figure 11-7. 

The listing contains a copy of the source input plus additional information. Two 
columns of numbers appear to the left of the source image. The first column provides 
a sequential numbering of PL/M statements. Error messages, if any, refer to these 
statement numbers. The second column gives the block nesting depth of the corres- 
ponding statement. 

Lines included with the INCLUDE control are marked with an equal sign ( = ) just to 
the left of the source image. If the included file contains another INCLUDE control, 
lines included by this nested INCLUDE are marked with an = 1 . For yet another 



PL/fl-flt COMPILER Stack nodule mm/dd/yy hh:mm:ss PAGE 1 

system-id PL/M-flb Vx.y COMPILATION OF MODULE STACK 
OBJECT MODULE PLACED IN stack. obj 

COMPILER INVOKED BY: plmfit stack-src CODE XREF TITLEtStack Module) 



1 STACK: DO; 

/* This module implements a BYTE stack with push and pop */ 

2 1 DECLARE S(1DD) BYTEt /* Stack Storage */ 

T BYTE PUBLIC INITIAL(-l); /* Stack Index */ 

3 1 PPUSH: PROCEDURE (B) PUBLIC; /* Pushes B onto the stack */ 
H 2 DECLARE B BYTE; 

S S S(T:=T+1) = B; /* Increment T and store B */ 

t 2 END PPUSH; 

7 1 PPOP: PROCEDURE BYTE PUBLIC;/* Returns value popped from stack */ 

fi 2 RETURN S((T:=T-1)+1); /* Decrement Ti return S(T+ 1) */ 

■5 2 END PPOP; 

10 1 END STACK; /* Module ends here */ 



Figure 11-7 Program Listing 
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level of nesting, = 2 is used to mark each line, and so forth up to the compiler's limit 
of nesting levels (see Appendix B). These markings make it easy to see where in- 
cluded text begins and ends. 

Should a source line be too long to fit on the page in one line, it is continued on the 
following line. Such continuation lines are marked with a hyphen (-) just to the left of 
the source image. 

The CODE control can be used to obtain the assembly code produced in the transla- 
tion of each PL/M statement. Figure 11-8 shows the assembly code listing for the 
program given in Figure 11-7. This code listing appears in six columns of informa- 
tion in a pseudo-assembly language format: 

1 . Location counter (hexadecimal notation) 

2. Resultant binary code (hexadecimal notation) 

3. Label field 

4. Opcode mnemonic 

5. Symbolic arguments 

6. Comment field 

Not all six of the columns will appear on all lines of the code listing. Compiler 
generated labels (e.g., those that mark the beginning and ending of a DO WHILE 
loop) are preceded by an AT sign (@). The comments appearing on PUSH and POP 
instructions indicate the stack depth associated with the stack instruction. 

1 1 .3.2 Symbol and Cross-Reference Listing 

If specified by the XREF or SYMBOLS control, a summary of all identifier usage 
appears following the program listing. Figure 11-9 shows the cross-reference listing 
of the program given in Figure 11-7. 

Depending on whether the SYMBOLS or XREF control was used to request the 
identifier usage summary, five or seven types of information are provided in the 
symbol or cross-reference listing. They are as follows: 

1 . Statement number where the identifier was defined. 

2. Relative address associated with the identifier. 

3. Size of the object identified (in bytes). 

4. The identifier. 
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PL/M-8b COMPILER Stack Module mm/dd/yy hh:mm:ss PAGE 2 

ASSEMBLY LISTING OF OBJECT CODE 

; STATEMENT # 3 





PPUSH 


PROC 


NEAR 


DDDD 


ss 


PUSH 


BP 


UUU 1 


nnrf 
□ DLL 


MAW 

nov 


or i 2s H 


DD03 


SA1EL-400 


MOV 


IUT 


DDD7 


FEC3 


INC 


BL 




n n i ri 1 1 n n 


MOV 


T i BL 


GOOD 


B700 


MOV 


BHiOH 


ODDF 


6AMbOM 


MOV 


AL,[BP].B 


DDIS 


66670000 


MOV 


S[BX] n AL 


001b 


SD 


POP 


BP 


0017 


CA0200 


RET 


2H 




PPUSH 


ENDP 






PPOP 


PROC 


NEAR 


DD LA 


SS 


PUSH 


BP 


001B 


6BEC 


MOV 


BP.SP 


001D 


8AlEb400 


MOV 


BLiT 


0021 


FECB 


DEC 


BL 


0023 


661Eb400 


MOV 


TtBL 


0027 


FEC3 


INC 


BL 


002T 


B700 


MOV 


BH-.OH 


002B 


6A670000 


MOV 


ALiS[BX] 


002F 


SD 


POP 


BP 


0030 


C3 


RET 





\ STATEMENT # S 

i STATEMENT • b 

i STATEMENT * 7 

\ STATEMENT # 6 



i STATEMENT # 1 

PPOP ENDP 

Figure 11-8 Code Listing 
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PL/n-Sb COflPILER Stack Module 

CROSS-REFERENCE LISTING 



m/dd/yy hh:m:ss PAGE 3 



DEFN ADDR SIZE NAMEi ATTRIBUTES, AND REFERENCES 



3 □□□1H 1 B BYTE IN PROC(PPUSH) PARAMETER AUTOMATIC M S 

7 DDI AH E3 PPOP PROCEDURE BYTE PUBLIC STACK=ODOEH 

3 DDDOU 2b PPUSH PROCEDURE PUBLIC STACK=QOOHH 

2 DDDDH 100 S BYTE ARRAY(IDD) 5* fi 

1 DDDDH STACK MODULE STACK=OOOOH 

5 DObMH 1 T BYTE PUBLIC INITIAL S S* fl fi* 



Figure 11-9 Cross-Reference Listing 



5 . Attributes of the identifier (including expansion for LITERALLYs and scoping 
information for local variables and parameters). For PL/M-386, these attributes 
reflect the WORD32/WORD16 terminology of the source file. 

6. Statement numbers where the identifier was referenced (XREF control only). 

7. Statement numbers where the identifier was assigned a value (XREF control 
only). 

Notice that a single identifier can be declared more than once in a source module 
(i.e., an identifier defined twice in different blocks). Each such unique object, even 
though named by the same identifier, appears as a separate entry in the listing. 

The address given for each object is the location of that object relative to the start of 
its associated section. The object's attributes determine which section is applicable. 

Identifiers in the SYMBOLS or XREF listing are given in alphabetical order with the 
following exception: members of structures are listed, in order of declaration, imme- 
diately following the entry for the structure itself. Indentation is used to differentiate 
between these entries. 

The XREF listing differentiates between items 6 and 7 by adding the asterisk (*) 
character to statement numbers where a value is assigned. For example, if statement 
17 read: 

1 = 1+1; 

the list of statement numbers for I would include 17 and 17*, indicating a reference 
and an assignment in statement 17. 
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The AUTOMATIC attribute indicates that the identifier was declared as a parameter 
or as a local variable in a REENTRANT procedure and therefore is allocated dynam- 
ically on the stack. 

11.3.3 Compilation Summary 

Following the listing (or appearing alone if NOLIST is in effect) is a compilation 
summary. Eight pieces of information are provided: 

• Code area size gives the size in bytes of the code section of the output module 
(not including constants, if any). 

• Constant area size gives the size in bytes of the constant area. The constant area 
will be included with either the code or data section in the output module, de- 
pending on the specified compiler controls. 

• Variable area size gives the size in bytes of the data section of the output module 
(not including constants, if any). 

• Maximum stack size gives the size, in bytes, of the stack section allocated for the 
output module. 

• Lines read gives the number of source lines processed during compilation. 

• Program warnings give the number of warning messages issued during 
compilation. 

• Program errors give the number of error messages issued during compilation. 

• Dictionary summary gives the actual memory and disk space used by the dictio- 
nary during compilation. 

Figure 11-10 is an example of the compilation summary. 
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MODULE INFORMATION: 



CODE AREA SIZE 
CONSTANT AREA SIZE 
VARIABLE AREA SIZE 
MAXIMUM STACK SIZE 
14 LINES READ 
D PROGRAM WARNINGS 
D PROGRAM ERRORS 

DICTIONARY SUMMARY: 

4KB MEMORY USED 
DKB DISK SPACE USED 

END OF PL/M-flb COMPILATION 

Figure 11-10 Compilation Summary 



= DD31H HID 

= DDDDH DD 

= DDbSH 1D1D 

= 0004H 4D 
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SAMPLE PROGRAM 

12.1 Introduction 

This chapter discusses a sample program consisting of three modules named FREQ, 
OPEN, and PRINT. The purpose of this program is to illustrate the use of the PL/M 
language. The program is written in PL/M-86, compiled with the PL/M-86 compiler, 
and combined with the LINK86 utility. 

The program takes an input file, counts the uppercase and lowercase alphabetic char- 
acters, and determines the percentage of use for each character. This is printed either 
to the screen or, if one is specified, to an output file. The program's output lists the 
number of times each character is used (for uppercase, for lowercase, and for both 
uppercase and lowercase), and the percentage of use for each character. The source 
program listings are shown in Figures 12-1 through 12-3. 

In addition to the main program modules (FREQ, OPEN, and PRINT), this program 
also has two include files. The include files, defns.inc and udi.inc (see Figures 12-4 
and 12-5), contain definitions that are used in the program modules. The defns.inc 
include file consists of global variable definitions. The udi.inc include file consists of 
the universal development system interface (UDI) definitions. The UDI definitions 
are used for operating system interface (e.g., file manipulation). Figure 12-6 is an 
example of the program output. 

The following sections describe the source code in each of the program modules. The 
line numbers in the figures are not part of the source code. The line numbers have 
been added to simplify the discussion of the source code. 

12.2 FREQ Module 

FREQ is the main module. The source code is shown in Figure 12-1. Note the line 
numbers in the figure. These are not part of the source code, nor are they the line 
numbers that the compiler would assign. The line numbers have been added to sim- 
plify the discussion of the source code. 

The program lines that begin with a dollar sign ($) are compiler control lines. Lines 
that begin with a dollar sign instruct the compiler and are not part of the source 
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program. In any position other than the first character (or the position specified with 
the LEFTMARGIN control), the dollar sign is an insignificant character and can be 
used as a separator to simplify the reading of variable names. 



1 SDEBUG PU(75) 

2 freq:D0i 

3 ^INCLUDE (defns-inc) 

4 SNOLIST 

5 /*** LIST of UDI procedures is in OPEN-PLM ***/ 
b ^INCLUDE (udi-inc) 

7 $LIST 

fl open$f iles:PROCEDURE EXTERNALS 
1 END open$files; 

10 print$stats:PROCEDURE(arr$ptr-, arr$len) EXTERNALS 

11 DECLARE arr$ptr POINTER; 
IS DECLARE arr$len WORD; 

13 END print$stats; 

14 DECLARE buf(flO) BYTE; 

15 DECLARE console CONNECTION EXTERNAL; 
lb DECLARE i. BYTE; 

17 DECLARE infile CONNECTION EXTERNAL; 

Ifl DECLARE lfreq(Eb) Freq_Struc; 

11 DECLARE num$read BYTE; 

20 DECLARE outfile CONNECTION EXTERNAL; 

21 DECLARE quit$time BYTE INITIAL(False) ; 

22 DECLARE status WORD; 

23 DECLARE total WORD PUBLIC INITIAL (0); 

24 REJECT 

25 main: 

2b CALL open$files; 

27 CALL init$real$math$unit; 

2fl DO i = to LENGTH(lfreq) ; 



21 lfreq(i) . let. low = D; 

30 lfreq(i) -let-up = 0; 

31 lfreq(i) -percent = 0-0; 

32 END; 



Figure 12-1 Source Code for FREQ Module 
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33 



/*** Now-, read the files ***/ 



34 read$f ile:C0 WHILE (NOT quit$time)i 

35 numSread = dq$read(inf ile-,abuf -.LENGTH(buf ) -.Slstatus) i 
3b IF num$read LENGTH (buf ) THEN quit$time = True; 

37 DO i = D to num$read; 

3fl total = total + l; /*** Total keeps track of ALL characters ***/ 
31 /*** read-, not just the letters. ***/ 

40 sh_uhich_letter:IF (buf(i) >= 'A' AND buf(i) <= 'Z') THEN 
Ml lfreq(buf (i )-' A ')• let-up = If req (buf ( i ) - ' A ' ) . let • up + 1; 

45 ELSE IF (buf(i) >= 'a' AND buf(i) <= 'z') THEN 

43 lfreq(buf ( i ) - ' a ' ) • let • low = If req (buf ( i ) - ' a ' ) . let . low + ii 

44 END; /*** Loop i = D to numSread ***/ 

45 read$file:END^ 
Mb stats: 

47 CALL print$stats(aifreq-,LENGTH(lfreq) ) i 
4fl CALL dq$exit(D)i 

4=1 END freqi 

Figure 12-1 Source Code for FREQ Module (continued) 



Line 1 specifies the DEBUG control and the pagewidth. The DEBUG control in- 
structs the compiler to collect debug information such as the statement number and 
relative address of each source program module (see the DEBUG/NODEBUG entry 
in Chapter 11). PW(75) specifies an output page 75 characters wide. 

Line 2 names the module and establishes the beginning of the module's DO block. As 
stated in Chapter 1 , a module must begin with a labeled DO statement and end with 
an END statement. 

Lines 3 through 6 specify the include files to be used in the program module. Line 4 
indicates to the compiler to not list anything until the LIST control is encountered, 
which happens at line 7. 

Line 5 is a user comment and will not be interpreted by the compiler. User comment 
lines begin with a slash/asterisk (/*) combination and end with an asterisk/slash (*/) 
combination. 

Lines 8 through 23 are the procedure and variable declarations used in the FREQ 
module. Note the EXTERNAL declarations in lines 8 through 13. These procedures 
are declared EXTERNAL, which means that the procedure is defined in another 
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module. The calling module must declare the procedure as EXTERNAL. The mod- 
ule in which these procedures are defined must declare the procedures as PUBLIC. 

The variable declarations (see lines 15, 17, and 20) are also EXTERNAL. The same 
rules apply for variables as for procedures. The calling module must declare the 
variable as EXTERNAL and the defining module must declare the variable as 
PUBLIC. If the variable definition is included in the calling module, the definition 
must be identical to the definition in the declaring module. 

Line 18 declares the lfreq structure, which is declared in the defns.inc file (see Figure 
12-4). Line 21 declares quit$time as a variable (with the INITIAL attribute) of type 
BYTE. In an initialization, the initialization attribute must be placed after the variable 
attributes. In line 23, total is declared as a variable of type BYTE. Note also the 
PUBLIC declaration. This indicates that this variable can be used by other modules 
within the program (if it is declared EXTERNAL within the module which uses it). 

Line 24 specifies the beginning of a new page (used when the program listing is 
printed). 

The program begins at line 25. Line 26 calls the open$files procedure (declared as 
EXTERNAL in line 8). This procedure opens the input file, and if one is specified, 
the output file. Line 27 calls the compiler built-in procedure, init$real$math$unit. 
This call is required to initialize the REAL math facility (the numeric data extension) 
for subsequent operations. 

Lines 28 through 32 consist of more initializations. These lines set (or reset) the 
values of the structure variable used in the module. Freq_struc is an array of nested 
structures (see Chapter 4). Freq_struc is a 26 element array (one element for each 
letter in the alphabet). Each element of the freq_struc array contains the let structure, 
which consists of a letter and a percent. Nested within the let structure is another 
structure (low and up). This structure holds the count of uppercase and lowercase 
characters. To see how freq_struc is declared, refer to Figure 12-4. 

Lines 34 through 45 show an example of a nested DO block. With PL/M, DO blocks 
can be nested up to 1 8 levels. Line 37 begins a second DO block within the DO block 
that begins at line 34. The DO block nested within the first DO block ends at line 44. 
The first DO block ends at line 45. 

Lines 34 through 36 use the UDI function, dq$read, to read from a file (infile). A 
specified number of characters are read from the file into an array. The array is buf 
and the number of characters read is LENGTH (buf). The value of buf was set in line 
14. LENGTH is a built-in function (see Chapter 11) that returns the number of 
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elements in an array. The UDI function, dq$read, returns the number of characters 
read (num$read) and an error code (status). For more information about UDI func- 
tions, refer to the run-time support manual. 

The nested loop (lines 37 through 44) keeps totals for all the characters read, the 
uppercase letters read, and the lowercase characters read. This entire loop repeats 
until the number of characters read in from the input file is less than 80 (this indicates 
that the input file is empty). 

Line 47 calls the external procedure print$stats. This procedure is defined in the 
PRINT module. Line 48 calls a UDI procedure, dq$exit. Finally, line 49 ends the 
FREQ module. 

12.3 OPEN Module 

The OPEN module takes care of the majority of the file-handling procedures for the 
program. This module makes extensive use of the UDI procedures provided by the 
run-time support library. The source code is shown in Figure 12-2. Note that the line 
numbers in the figure are not part of the source code, nor are they the line numbers 
that the compiler would assign. The line numbers have been added to simplify the 
discussion of the source code. 



1 $DEBUG PU(75> 
E open:D<K 
3 SNOLIST 

H ^INCLUDE (defns-inc) 
S $LIST 

b REJECT 

7 $INCLUDE(udi.inc) 
fi REJECT 

1 DECLARE console CONNECTION PUBLIC; 

10 DECLARE infile CONNECTION PUBLICS 

11 DECLARE outfile CONNECTION PUBLICS 

12 DECLARE NeedFileC*) BYTE INITIAL (' Enter input file name: 

13 DECLARE OpenError < * ) BYTE INITIAL ('Error opening input file' iCR-iLF) i 

1M open$files:PROCEDURE PUBLICS 

Figure 12-2 Source Code for OPEN Module 
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IS DECLARE delim BYTE; 

lb DECLARE console$in CONNECTIONS 

17 DECLARE buffer(AO) BYTEi 

lfl DECLARE status UORD; 

V! DECLARE in$buf(61) BYTE ; 

2D DECLARE i BYTE; 

21 DECLARE num$read BYTE; 

22 console = dq$create(a(4-, ' :C0: ' ) iBstatus) \ 

23 CALL dq$open(consolenUriteOnly-iO-iaistatus) ; 

S M /*** Process the command linen it consists of three partsi 
2S 1) the program name (lf-exe) 

2b 2) the input file name n if this is not present then 

27 ask for it 

2fl 3) the output file namen if this is not present then 

2T the output goes to the console ***/ 

3D /*** Read past the program name ***/ 

31 delim = dq$get$argument Obuf f er n 3status) \ 

32 /*** Find out name of the input file ***/ 

33 IF delim = CR THEN 
31 DO; 

35 /*** No input file specified-i ask for it ***/ 
3b CALL dq$write(console-,aNeedFile-.LENGTH(NeedFile) -.astatus) ; 

37 console$in = dq$attach(3C4i ' :CI: ' ) ^status) ; 

36 CALL dq$open(console$iniReadOnlynOiastatus) ; 

3^ schDDl:num*read = dq$read(console$in n ain$buf i LENGTH (in$buf) iSstatus) ; 

40 CALL dq$close(console$in n astatus) ; 

41 /*** Convert the read in buffer to the infile buffer ***/ 

42 sh_inf ile:buf fer(D) = num$read; 

43 DO i = D to num$read; 

44 IF (in$buf(i) <> CR) AND (in$buf(i) <> LF) 

45 THEN buffer(i+l) = in$buf(i); 
4b ELSE 

47 buffer(D) = buffer(D) - 1; /*** adjust count for CR/LF ***/ 

46 END; /*** end of DO loop to Convert buffer ***/ 
41 end; 

SD ELSE 

51 delim = dq$get$argument ( 3buf feri3status) ; 

52 /*** END; get file name to process ***/ 

53 /*** Open input file ***/ 



Figure 12-2 Source Code for OPEN Module (continued) 
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54 infile = dqSattach ( 3buf feriSstatus) i 

55 CALL dq$open(infileiRead0nly n 5iastatus)i 
5b IF status <> E$OK THEN D0=, 

S7 CALL dq$write(console-.aOpenError-.LENGTH(OpenError) n 3status)i 

56 CALL dq$exit(l)n 

51 END i /** status is not ok **/ 

bO /*** Find out if an output file was specified-, if so-. ***/ 

bl /*** open it-, if not use the console output ***/ 

b5 IF delim = CR THEN 

b3 outfile = console^ 

b4 ELSE DO =, 

bS delim = dq$get$argument ( 3buf feriBstatus) i 

bb outfile = dq$create(3buf fer-iSstatus) i 

b? CALL dq$open(outf ile-ililriteOnlyiS-iastatus) i 

bfl END i 



bl END open$f ilesi 
70 END openi 

Figure 12-2 Source Code for OPEN Module (continued) 



Line 1 instructs the compiler to collect debug information and sets the page width for 
printed output (see Section 12. 1). Line 2 names the module and establishes the begin- 
ning of the module's DO block. Lines 3 through 8 specify the inclusion of the pro- 
gram's include files, turn the listing function on and off, as well as specify a few new 
pages for printed output ($EJECT). 

Lines 9 through 1 1 define and declare some PUBLIC variables. Because these vari- 
ables are declared PUBLIC, they can be used in another module. The calling module 
must declare the variable as EXTERNAL. The variable definition is included in the 
calling module, and it is the same as the definition in the defining module. 

Lines 12 and 13 are error messages to be used by the OPEN module if the necessary 
information is not included in the invocation line (which causes an error). Note the 
use of the asterisk in each of these lines. The asterisk is used as an implicit dimension 
specifier. The implicit dimension specifier can be used when either the size of the 
array is unknown or insignificant. In this instance, the size of the array is unknown. 
The use of the implicit dimension specifier in lines 12 and 13 specifies that the 
NeedFile array and the OpenError array will have the same number of elements as 
the value list (the number of characters in the message). 

Line 14 begins the open$files procedure. This procedure is declared as public (it is 
called by the FREQ module) and continues until the end of the module (line 69). 
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Lines 22 and 23 get and open a connection with the console using predefined UDI 
procedures. Note the use of the @ operator in these two lines. The first time the @ 
operator is used in line 22, it is used to allocate storage for the constants 4 and :CO:. 
The remaining uses of the @ operator are for location references. This means that the 
value of the reference (e.g., the value of ©status) is the actual run-time location of 
the variable. 

Lines 24 through 52 use the UDI procedure, dq$get$argument, to parse the input 
line. Line 31 gets the first part of the command line, as well as the delimiter used to 
separate this part of the command line from the next part (if there is any). Line 33 
tests the delimiter. If the delimiter is a carriage return then lines 34 through 49 are 
processed. Lines 34 through 49 request a file name. If the delimiter is not a carriage 
return then dq$get$argument is called again. This routine is also called by lines 60 
through 68 to determine whether the program output should go to a file or to the 
console. 

Line 3 1 passes the invocation line to the following IF/THEN/ELSE construct (lines 
33 through 51). The IF/THEN/ELSE construct checks for an input file name. If no 
input file is specified, line 36 uses the NeedFile string declared in line 12. This 
prompts the user to enter an input file name. If no input file name is specified in 
response to the prompt, the program aborts. Otherwise, the string is converted as 
discussed in the preceding paragraph. 

Lines 43 through 48 convert the file name to a UDI call. 

Lines 50 and 51 are the ELSE clause of delim = CR. 

Lines 53 through 59 open the input file. Lines 60 through 68 open an output file, if 
one is specified. Otherwise, the program data is sent to the console. 

Line 69 is the end statement for the open$files procedure and line 70 is the end 
statement for the OPEN module. 
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12.4 PRINT Module 



The PRINT module performs the program calculations and prints the information 
(either to the console or to the specified output file). The source code is shown in 
Figure 12-3. Note the line numbers in the figure. These are not part of the source 
code, nor are they the line numbers that the compiler would assign. The line numbers 
have been added to simplify the discussion of the source code. 



1 5DEBUG PW(75) 

2 print:D0; 

3 SNOLIST 

4 ^INCLUDE (defns-inc) 

5 ^INCLUDE (udi-inc) 
b $LIST 

7 DECLARE BLANK$OUT$LINE LITERALLY 

fl 'DO j = D TO LENGTH(line) iline(j) = SPACEiEND' ; 

1 DECLARE LETTER LITERALLY '3'; 
ID DECLARE LOWER LITERALLY '54'; 
11 DECLARE PCT LITERALLY '33':, 
IE DECLARE SUM LITERALLY 'fl'; 

13 DECLARE UPPER LITERALLY 'lb'; 

14 DECLARE outfile CONNECTION EXTERNALS 

15 DECLARE toplineU) BYTE INITIAL 

lb ('LETTER TOTAL UPPER LOWER Z '-,CR-,LF); 

17 /** ( A DDDDD ODDDO 00000 000-0 ***/ 

lfl /** ( 12345b7fl1 1234Sb7fl1 1234Sb7fl<1 1234Sb7fl1 12345b7fl1 ***/ 

11 DECLARE total WORD EXTERNAL ; 

20 DECLARE totalSstr (S) BYTE INITIAL ('TOTAL'); 

21 int2asc:PR0CEDURE(number-,stg$ptr-,count) BYTE; 

22 DECLARE number WORD; 

23 DECLARE stg$ptr POINTER; 

24 DECLARE count BYTE; 

25 DECLARE i BYTE-, j BYTE; 
2b DECLARE max DWORD; 

27 DECLARE string BASED stg$ptr(l) BYTE; 

2fl DECLARE tmpstg(lO) BYTE; 

21 max = 1; 

30 DO i = 1 TO count; 

31 max = 10 * max; 

32 END; 

33 max = max - 1; 

Figure 12-3 Source Code for PRINT Module 



Sample Program 



12-9 



34 
35 
3b 



DO i = □ TO LAST(tmpstg); 
tnpstg(i) = SPACE; 
END'-, 



37 
3fl 
3=1 
40 
41 
42 
43 



IF number <= max THEN DO; 



IF number □ THEN GOTO loop; 



i = Di 



loop : 

tmpstg(i) = (number HOD ID) " ' D ' ; 

i = i * 1; 

number = number/ID; 



44 
45 
4b 
47 
48 
41 
50 
51 



DO j = TO count; 



string(count-j) = tmpstg(j); 

end; 



end; 
else do; 



DO i = to count; 
string(i) = '*'; 

end; 



52 end; 

53 RETURN ( i ) ; 

54 END int2asc; 

55 rea 12asc: PROCEDURE (number -,stg$ptr-, count ) ; 
5b DECLARE number REAL; 

57 DECLARE stg$ptr POINTER; 

5fl DECLARE count WORD; 

51 DECLARE i BYTE-, j BYTE; 

bD DECLARE int$len BYTE; 

bl DECLARE string BASED stg$ptr(l) BYTE; 

b2 DECLARE tmpnum DWORD ; 

b3 DECLARE tnpstg(lO) BYTE; 

b4 /*** Convert the number to an INTEGER to convert itn assume one ***/ 
b5 /*** decimal place ***/ 

bb tmpnum = DUORD(number*lD-D); 

b7 int$len = int2asc(tmpnum n atmpstg-iLAST(tmpstg) ) ; 

bfl IF intSlen = 1 THEN DO; /*** Handle the case where the number ***/ 
bl /*** is less than 1-0 ***/ 

70 int$len = 2; 

71 tmpstg(LAST(tmpstg)-l) = ' ' ; 

72 end; 



Figure 12-3 Source Code for PRINT Module (continued) 
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73 DO i = D TO int*len-Ei 

74 string(count-i) = tmpstg(LAST(tmpstg)-i) ; 

75 END ; 

7k string(count-int$len) = ' . ' "i 

77 string(count-int$len-l) = tmpstg(LAST(tmpstg)-int$len+l) i 

76 END real2asc; 
71 $EJECT 

60 print$stats:PROCEDURE (arrSptr-, arr$len) PUBLIC; 
fll DECLARE arr$ptr POINTER; 

62 DECLARE arr$len WORD; 

63 DECLARE array BASED arr$ptr(l) Freq_Struc; 
84 DECLARE i BYTE-, j BYTE ; 

AS DECLARE line(SD) BYTE; 

fib DECLARE status WORD; 

67 DECLARE tmp BYTE; 

66 DECLARE ii byte; 

61 call dq$write(outf ile-,atopline-,LENGTH(topline) -,3status) ; 

10 printlines : DO ii = D TO arr$len-l; 

11 blank$out$line; 

12 line(LETTER) = ii + 'A'; 

13 /*** Get the total and convert number to ascii ***/ 

14 tmp = int2asc( (array(ii) ■ let- low + array(ii) ■ let-up) -, 31ine(SLH1) -,5) \ 

15 tmp = int2asc (array ( i i )- let - low-, 31ine(L0WER) -,5) ; 
lb tmp = int2asc (array(ii) - let-upi aiine(UPPER) -<S) ; 

17 array(ii) -percent = REAL ( (array ( ii )• let ■ low) + (array(ii) -let-up) ) / 

16 REAL ( total ) * 100-0; 

11 CALL real2asc ( array ( i i ). percent -, aiine(PCT) -,5) ; 

100 line(LASTdine)-l) = CR; 

101 line(LASTdine) ) = LF ; 

102 CALL dq$write(outf i 1 e -, 31 ine -, LENGTH ( 1 ine ) -.Bstatus) ; 

103 END printlines; /*** print loop ***/ 

104 blank$out$line; 

IDS DO i = TO LAST(total$str) ; 

lOt line (LETTER-2"i ) = totalSstr ( i ) ; 

107 END ; 

106 tmp = int2asc( total-, SlineCSUfl) -.5) ; 

101 call dq$write(outf ile-,31ine-,LENGTH(line) -.Sstatus) ; 



110 END printSstats; 

111 END print; 

Figure 12-3 Source Code for PRINT Module (continued) 
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Line 1 instructs the compiler to collect debug information and sets the page width for 
printed output (see Section 12.1). Line 2 names the module and establishes the begin- 
ning of the module's DO block. Lines 3 through 6 specify the inclusion of the pro- 
gram's include files and turn the listing function on and off. 

Lines 7 through 13 are a group of literally definitions. A literally definition is used to 
create an alternate name for a sequence of characters. Lines 7 and 8 declare 
BLANK$OUT$LINE as the alternate name for the DO loop used to blank out the 
output line buffer. Additionally, after line 13, the number 16 will reference upper (for 
uppercase character). This is a useful function to eliminate keystrokes, to make the 
program more readable, and to declare quantities that may be fixed in one module, 
but subject to change in another module. 

Lines 14 through 20 contain more declarations, as well as the header string for the 
output (line 16). 

Lines 21 through 54 perform an integer to ASCII translation. Lines 55 through 78 
perform a real number to ASCII translation. 

Line 80 is the beginning of the print$stats procedure. The print$stats procedure is 
called by the FREQ module, therefore it is declared PUBLIC in this module. Note 
the based variable in line 83. In this instance, the location of array is based on the 
address of arr$ptr, which is passed into the print$stats procedure. The size of the 
array is unknown (except through the parameter). The 1 enclosed in parentheses 
enables the use of arr$ptr as an array (any number can be used). 

Line 89 calls a UDI procedure that writes to an external connection declared in the 
OPEN module. Note the use of BLANK$OUT$LINE in line 91. 

Lines 90 through 103 are a DO loop that is repeated for each letter in the alphabet. 
For each character, the line(LETTER) array is filled with the letter, the total, the total 
uppercase, the total lowercase, and the percent. This information is then sent to the 
specified output device (the console or a file). 

Lines 93 through 96 call the procedure to convert the total into ASCII characters. 
Lines 97 and 98 figure the percentage of use for each character. Line 99 calls the 
procedure to convert the percentage to ASCII characters. Lines 100 and 101 insert a 
carriage return and a line feed in the console display or in the output file. 

Line 1 10 ends the print$stats procedure and line 1 1 1 ends the PRINT module. 
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12.5 Include Files 



As stated in Section 12.1, there are two include files with this program (see Figures 
12-4 and 12-5). 



DECLARE DCL LITERALLY ' DECLARE ' i 



DCL 


LIT 


LITERALLY 


' LITERALLY 1 i 


DCL 


CR 


LITERALLY 


' DDH ' i 


DCL 


LF 


LITERALLY 


' DAH ' i 


DCL 


True 


LITERALLY 


' DFFH ' 


DCL 


False 


LITERALLY 


' DDDH ' =i 


DCL 


Freq__Struc 


LITERALLY 


' STRUCTURE (let STRUCTURE 



(low LIORDn up lilORD) i 
percent REAL) ' i 

DCL SPACE LITERALLY ' D20H ' i 

Figure 12-4 Include File — defns.inc 



Figure 12-4 is the defns.inc file. It contains definitions for terms used in common by 
all of the modules in the program (excluding the UDI definitions). Note the declara- 
tion of a structure in this include file (freq_struc). This structure is used in the 
PRINT module and the FREQ module. This structure declaration illustrates several 
levels of nesting. Structures can be nested up to 32 levels. 

Figure 12-5 is the udi.inc file. It contains UDI definitions that are used throughout 
the modules. The UDI is a predefined set of procedure calls that enables use of 
operating system functions. For more information on UDI definitions, see the run- 
time support manual. 
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DECLARE CONNECTION literally 'UORD'i 
DECLARE Readonly LITERALLY 'I'i 
DECLARE WriteOnly LITERALLY 
DECLARE E$OK LITERALLY ' OH ' i 

dq$attach:procedure (path$p-iexcept$p) CONNECTION externals 
declare path$p pointeri declare except$p pointeri 
end dq$attachi 

dqSclose : procedure (af tn-iexception$ptr ) externali 
declare aftn CONNECTION-. exception$ptr pointer; 
end dq$closei 

dq$create:procedure (path$p-.exception$ptr) CONNECTION externals 
declare (path$p-,exception$ptr) pointeri 
end dq$createi 

dq$exit:procedure ( completion$code) externali 
declare completion$code wordi 
end dq$exiti 

dq$get$argument:PROCEDURE (arg$ptr-, ex$ptr) BYTE EXTERNALS 
declare arg$ptr POINTER^ ex$ptr POINTERS 
END dq$get$argumenti 

dq$open : procedure (af tn-.mode-inum$buf -iexception$ptr ) externali 
declare aftn CONNECTION-! exception$ptr pointeri 
declare (it\ode-inum$buf ) bytei 

end dq$openi 

dq$read:PROCEDURE(aftn-,buf$ptr-,count-,ex$ptr) lilORD EXTERNALi 
declare aftn CONNECTIONi 
declare buf$ptr POINTERi 
declare count UORDi 
declare ex$ptr POINTERi 
END dq$readi 

dq$write : procedure (aftn-,buffer-iCount-iexception$ptr) externali 
declare aftn CONNECTIONi 
declare count wordi 

declare (buffer-,exception$ptr) pointeri 
end dq$writei 

Figure 12-5 Include File — udi.inc 
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EXTENDED 
SEGMENTATION MODELS 

13.1 Overview 

Program segmentation is the division of a program into memory segments. It is a 
technique used to optimize the code produced by the compiler. The segmentation 
controls (SMALL, MEDIUM, COMPACT, and LARGE) manage program segmen- 
tation by defining the physical relationship in memory of a program's code, data, 
constants, and stack. They determine which (if any) segments get combined. For 
example, specifying the SMALL segmentation control for a program module locates 
all of the module's code, data, constants, and stack in two segments, CODE and 
DATA. When the program's modules are combined, sections from the separately 
compiled modules are combined into segments according to the specified segmenta- 
tion controls. This optimizes code because references to locations in the same mem- 
ory segment are more efficient. 

Extended segmentation models are a super-set of the segmentation controls. The 
extended segmentation models (which consist of the SMALL, COMPACT, and 
LARGE subsystems) provide enhanced program speed and aid in the construction of 
large programs. An extended segmentation model consists of a number of subsys- 
tems. A subsystem is a collection of program modules that use the same segmentation 
controls. A program is made up of one or more subsystems. With subsystems, 
program modules that are compiled with different segmentation controls can be 
combined. 

This chapter defines the use of extended segmentation models, and contains the fol- 
lowing sections: 

• Introduction 

• Segmentation controls architecture overview 

• Using subsystems 

• Syntax 

• Exporting procedures 

• Large matrix example (PL/M-386 specific) 
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13.2 Introduction 



Extended segmentation models provide the following programming advantages: 

• Efficient use of memory. 

• Access to the microprocessor's segmented architecture. 

• Storage reduction for external references to pointers and code. 

• Increased program execution speed for intersegment calls and data access. 

Additionally, to simplify the development of large programs, the segmentation con- 
trols can be used to partition the program into a collection of related subsystems. 

Partitioning a large program into a series of subsystems isolates code references 
within the same segment. The compiler processes each program module individually, 
assigning code, data and stack segments for each module (according to the specified 
segmentation control). As a source file is translated, the compiler generates a STACK 
segment for the program stack, as well as a DATA segment for the program data and 
a CODE segment for the program's executable code. When the program modules are 
combined, the CODE, DATA and STACK segments from all of the individual pro- 
gram modules are combined. Use of the segmentation controls ensures that the seg- 
ment names generated by the compiler are combined according to the overall 
structure of the program. 

A subsystem is either open or closed. An extended segmentation model can have only 
one open subsystem, but any number of closed subsystems. 

An open subsystem does not have a name and claims the program modules that are 
not claimed by another subsystem. Effectively, a program that uses only the segmen- 
tation controls is an open subsystem. Modules can be added to the open system 
without having to change the subsystem definition. 

A closed subsystem has a name and, optionally, a list of program modules used in the 
subsystem. To add a module to a closed subsystem, the subsystem definition must be 
changed. 
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13.3 Segmentation Controls Architecture Overview 



The segmentation controls described in Chapter 1 1 define the physical relationship in 
memory of program code, data, constants, and stack during program execution. 
When a PL/M source file is compiled, an object module conforms to a particular 
extended segmentation model. 

There are three extended segmentation models: SMALL, COMPACT, and LARGE. 
For the 8086 and the 80286 microprocessors, each segment can be as large as 64K 
bytes. For the 80386 microprocessor, each segment can be as large as 4G bytes. 

There are two submodels within each model: RAM and ROM. Specifying RAM 
places the program constants in the DATA segment. Specifying ROM places the 
program constants in the CODE segment. 

Tables 13-1 and 13-2 define the memory partitions and the placement of pointers in 
the various architectural models available with the segmentation controls. Table 13-1 
shows how memory is partitioned. Table 13-2 defines the register addresses and the 
pointer values. Table 13-3 defines the register addresses and the pointer values for the 
80386 microprocessor-specific ES register. Note that the POINTER variable value 
for the 80386 microprocessor using the SMALL ROM extended segmentation con- 
trols is 6 bytes. 
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Table 13-1 Segmentation Controls and Memory Partitions 



Control 


Segment Name 


CODE 


DATA 


STACK 


SMALL RAM 


code 


data 

constants 
stack 




SMALL ROM 


constants 
code 


data 
stack 




COMPACT RAM 


code 


data 

constants 


stack 


COMPACT ROM 


constants 
code 


data 


stack 


MEDIUM RAM* 


separate CODE segment 
for each module's code 


data 

constants 
stack 




MEDIUM ROM* 


OC|Jal ale uUUC ocyilltMIl 

for each module's code 
and constants 


UQ1Q 

stack 




LARGE RAM* 


^pnaratp nODF cipnmpnt 

ocl/ui die vv v_/ 1 — / i ocyi i ici n 

for each module's code 


^pnaratp DATA 

ocuqi die un i n 

segment for each 
module's data 
and constants 


stack 


LARGE ROM* 


separate CODE segment 
for each module's code 
and constants 


separate DATA 
segment for each 
module's data 


stack 



"The 80386 microprocessor uses only the SMALL and COMPACT segmentation controls. For 
the segmentation controls (NOT subsystems), MEDIUM is equivalent to SMALL and LARGE is 
equivalent to COMPACT. 



13-4 



Extended Segmentation Models 



Table 13-2 Segmentation Controls, Register Addresses and Pointer Values 





Register Address 


POINTER 


Control 


CS 


DS 


SS 


Variable 


Value 


SMALL 


vvUL ^"y ■ 


DATA ^pn 


DATA ^pn 


2-byte 


RAM 


Offcot-rofpronfP 

Ul loCl I CI CI CI l^C 


Off cot-rpfprpni**P 

Ul IOC l 1 CI CI CI IUC 


HaQ camp vnlnp 
i ido ocihic vaiuc 


offset 




rplativp tn 

ICIClllVC L\J L/O 


rplativ/p tn 


as DS 


only 












SMALL 


CODEseg. 


DATA seg. 


DATA seg. 


4-byte 


ROM 


Constant refer- 


Offset reference 


Has same value 


selector- 




ence requires 




as DS 


offset for 




selector-offset 




Offset-reference 


the 8086 




containing CS 






and 




value and offset 






80286; 




within rnnF 






6-byte 




segment 






selector- 




Dnrip rpfprpncp 






offset for 




requires offset- 






the 




reference relative 






80386 




toDS 








COMPACT 


CODE seg. 


DATA seg. 


STACK seg. 


4-byte 


RAM 


Selector-offset 


Selector-offset 


Selector-offset 


selector- 




reference 


reference 


reference 


offset 


COMPACT 


ouut seg. 


ouub seg. 


o iaok seg. 


4-byte 


ROM 


OCICUIUI \J\ loci 


Qoloptnr-nffcot 

OC1CL-IUI Ul 1 oc l 




selector- 




reference 


reierence 


rererencc 


offset 


MEDIUM 

1 VI l_ l_/ 1 \J IVI 


Current CODE 


DATA seg. 


DATA seg. 


4-byte 


RAM 


seg. 


Selector-offset 


Selector-offset 






Selector-offset 


reference 


reference 


offset 




reference 










Updated when 










PUBLIC or 










EXTERNAL 










procedure is 










activated 
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Table 13-2 Segmentation Controls, Register Addresses and Pointer Values 
(continued) 





Register Address 


POINTER 


Control 






SS 


Variable 


CS 


DS 


Value 


MEDIUM 


Current CODE 


I— » ATA 

DATA seg. 


|-\ ATA 

DATA seg. 


4-byte 


ROM 


seg. 


Selector-onset 


Selector-onset 


selector- 




OclcOlUf -Ul loci 


IClClCl IOC 


references 

1 CICI CI IOC 


offset 




I clcl cl lOc 










UfJUalcu Wi ICI I 










PI IRI IP nr 










FXTFRNAI 










(JlUL-CUUfc lo 










aULIValcU 








LARGE 


Current CODE 


Current DATA 


STACK seg. 


4-byte 


RAM 


seg. 


seg. 


Selector-offset 


selector- 




Qolootn r-nffcot 
ocicoiow uhoct 


OCICOIOM - UI lOCl 


references 

1 CICI CI IOC 


offset 




I clcl ciloc 


iclc! cTloc 








upudiwa wnen 


1 1 i""\/-l f^ + rt/H lA/riQrt 

upaaieu wnen 








PI IRI IP ~,r 
rUDLIL' Or 


PI IRI IP r.r 

rUbLIU or 








FXTFRNAI 

t_/\ i LnnnL 


FXTFRNAI 

L_/\ i cnnnL 








nrr\f£i/Hi i ro ic 
(JIUOcuUlc lo 


rM*/~ir , ciHi irti io 
prUOcUUic lo 








aOUVdlcU 


dOllvdlcU 






LARGE 


Current CODE 


Current CODE 


STACK seg. 


4-byte 


ROM 


seg. 


seg. 


Selector-offset 


cplpptor- 




Selector-offset 


Selector-offset 


reference 


offset 




reference 


reference 








Updated when 


Updated when 








PUBLIC or 


PUBLIC or 








EXTERNAL 


EXTERNAL 








procedure is 


procedure is 








activated 


activated 







The values given in Tables 13-1 and 13-2 are identical for the 80386 microprocessor. 
Additionally, the 80386 microprocessor has the ES register address. Table 13-3 states 
the values for the 80386 microprocessor-specific ES register. 
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Table 13-3 80386 Microprocessor-specific ES Register Segmentation 
Controls, Register Addresses and Pointer Values 



Control 


ES Register Address 


POINTER Variable Value 


SMALL RAM 
SMALL ROM 
COMPACT RAM 
COMPACT ROM 


DATA seg. 
Offset reference 

DATA seg. 
Offset reference 

DATA seg. 

Selector-offset reference 
DATA seg. 

Selector-offset reference 


4-byte offset only 
6-byte selector offset 
6-byte selector-offset 
6-byte selector-offset 



end 

PL/M-386 



The SMALL RAM segmentation control is the most efficient. Because all of the code 
resides in one segment, jumps and calls are always within the same segment (intra- 
segment). However, the SMALL RAM segmentation control provides less protection 
and cannot be used to pass pointers to library procedures unless the library procedure 
is also a SMALL RAM model. 



Use the COMPACT segmentation controls (COMPACT RAM and COMPACT ROM) 
for separate management of the code, data, and stack, or to improve segment-limit 
protection. To reference stack-based variables, the COMPACT segmentation controls 
use selector-offset references. This is less efficient than using offset-only references. 
However, data and constant references within a COMPACT segmentation control 
module are within the same segment (intra-segment). Note that if a COMPACT pro- 
gram must pass a data address to a procedure in a different subsystem, it must use a 
selector-offset reference. 

PL/M-86/286 

For the MEDIUM segmentation control, selector-offset references are used because 
there is more than one CODE segment. This enables pointer reference to procedures 
that reside in different CODE segments. Since there is more than one CODE seg- 
ment, far calls and jumps (4 byte, selector-offset) are necessary. However, offset-only 
references can be used for the data, constants, and stack. 
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PL/M-86/286 

(continued) 



end 

PL/M-86/286 



For the LARGE segmentation control, selector-offset references are used to enable 
pointers to procedures, data, and constants that reside in different CODE or DATA 
segments. Since there is more than one CODE segment, far calls and jumps are 
necessary. 



13.4 Using Subsystems 

Subsystems offer an efficient way to manage programs with large amounts of data, to 
share data between program modules, and to communicate with other programs. 

For example, subsystems are useful when several programmers are each writing a 
separate module for a highly structured program in which sharing data between mod- 
ules is accomplished with parameter passing, by value only. To maintain the integrity 
of each section's data requires that each section have its own DATA segment. In this 
way, code in one module of the program cannot mistakenly destroy data belonging to 
another section of the program. In this instance, each module could be a COMPACT 
subsystem, with its own CODE and DATA segments. 

As another example, a program performing I/O usually requires operating system 
support routines. In many cases, the operating system will operate at a higher protec- 
tion level than the application program. Thus, operating system procedure calls are 
intersegment calls. The application program views the operating system as a separate 
subsystem. Usually, operating system interface libraries are supplied to application 
programmers; these libraries perform the inter-subsystem communication details. If 
a program needs to make a direct operating system call without using a presupplied 
library, the program itself must define the necessary subsystem environments at com- 
pile time. 

It is usually more efficient to structure a large program with subsystems. With sub- 
systems the code and data can be partitioned into manageable pieces bigger than one 
module. Within each subsystem, calls and jumps are near (2 byte offset), references 
can be offset only, and the data of each subsystem is protected from being overwritten 
by other subsystems. Calls and jumps between subsystems are still far, and references 
between subsystems need to be selector-offset. In general, a program's structure is 
such that it is possible to break the program into pieces with a minimum number of 
intersegment calls, jumps, and references. 

For example, consider a program consisting of 10 modules, mod_l through mod_10. 
Modules 1 through 3 deal with input and initial processing. Modules 4 through 8 do 
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the main data processing. Modules 9 and 10 output the data. The following figure 
illustrates the structure of the program: 




data 
flow 



PROCESS 



(mod_4 
mod_5 
mod_6 
mod_7 
mod_8) 



data 
flow 



OUTPUT 



(mod_9 
mod_10) 



♦output 



The total code space required by this program exceeds 64K bytes, and the total data 
space also exceeds 64K bytes. Thus, for the 8086 and the 80286 microprocessors, 
LARGE is the only segmentation control that could be used. The LARGE segmenta- 
tion control provides each module with its own CODE and DATA segment. For this 
example, this results in a total of 21 segments (10 CODE, 10 DATA, and 1 STACK). 
For the LARGE segmentation control, all calls and jumps are far, and all intermodule 
references must be through selector-offset POINTERS. 



If, for example, COMPACT subsystems are used instead of the LARGE segmentation 
control, modules 1 through 3 can form one subsystem, call it SUB_INPUT. Modules 
4 through 8 can form subsystem SUB_PROCESS. Finally, modules 9 and 10 can 
form subsystem SUB_OUTPUT. The number of segments has been reduced to seven 
3 CODE, 3 DATA, and 1 STACK). Since most of the calls, jumps, and references 
now take place within only one of the subsystems, the program is much more effi- 
cient. The only far calls and jumps, and the only selector-offset references needed are 
those in the interfaces between the subsystems. 

PL/M-386 

For the 80386 microprocessor, a typical program does not require subsystems. The 
code space of 4 gigabytes and the data space of 4 gigabytes is quite sufficient for most 
programs. However, consider a program that processes a large amount of data such 
as a 10x1,000,000,000 REAL matrix. A REAL scalar consists of 4 bytes, so the total 
memory needed is 40 billion bytes. Rows could be used to partition the matrix. Each 
row would be 4 billion bytes, which would fit into a single DATA segment. 
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PL/M-386 — 

(continued) 

Ten COMPACT subsystems (named ROW1, ROW2, etc.) could be created, each 
containing a 1 -billion element REAL array. Procedures to store and retrieve particu- 
lar matrix elements can be written and called from the normal matrix processing 
code. See Section 13.6 for an example of this program. 

end 

PL/M-386 

It is not just dividing a program into subsystems that increases its efficiency. If all the 
even numbered modules had been placed in one subsystem, for instance, and all the 
odd numbered ones into another, the efficiency of the program would not have im- 
proved as it did when the modules were grouped into subsystems according to the 
logical structure of the program. 

Note also the following points: 

1. Not all subsystems must use the same segmentation control. For instance, if 
SUB_PROCESS in the preceding example is small enough, it could be a 
SMALL subsystem. 

2. If a SMALL subsystem is mixed with subsystems using other segmentation con- 
trols, the main program must be in SMALL. This is because anything compiled 
in SMALL assumes that DS and SS are identical. This will be so only if the main 
program is SMALL. Notice that in this case, the STACK segment resulting from 
the COMPACT and LARGE subsystems will not be used, since the stack of the 
main program is in the combined DATA-STACK segment of the SMALL model. 

3. SMALL RAM subsystems have the limitation that the SMALL segmentation 
control uses short (offset only) pointers. A SMALL RAM subsystem cannot 
receive a pointer from another subsystem, because it cannot save the selector 
portion. A SMALL RAM subsystem can, however, pass a pointer to a subsystem 
that is not SMALL RAM, because its own DS is known to it. (However, a 
SMALL RAM subsystem cannot pass a pointer (which points to a procedure), 
since DS is assumed as the selector to all pointers.) 

4. For the 8086 and the 80286 microprocessors, using all LARGE subsystems has 
the same effect as using the LARGE segmentation control without subsystems. 
However, using a mixture of LARGE and other subsystems may be useful. 

5. MEDIUM is a segmentation control only, not an extended segmentation model. 

Section 13.3 describes the memory layouts of programs using the standard segmenta- 
tion controls: SMALL/COMPACT/MEDIUM/LARGE. To understand the memory 
layouts of programs structured with subsystems, it is necessary to make the distinc- 
tion between compiling modules and combining modules into a program. 
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The compiler compiles only one module at a time. When modules are combined into 
a program, many CODE, DATA and STACK segments, which were generated during 
separate compilations, are combined. When combining program modules, all seg- 
ments with the same name are combined. The segmentation controls work by con- 
trolling the names of the segments generated by the compiler. This ensures that the 
segment names will be combined as desired when the modules are combined into a 
program. 

The standard SMALL segmentation control causes the compiler to name the CODE 
segment CODE, and the DATA-STACK segment DATA. Since under the standard 
SMALL model all CODE segments have the same name, and all DATA-STACK 
segments have the same name, they are combined when the modules are combined. 

A module belonging to a SMALL subsystem, on the other hand, takes the name of its 
CODE segment from the name of the subsystem. The name of its DATA-STACK 
segment is still DATA. Thus, a SMALL subsystem named SUB1 contains one CODE 
segment named SUBl_CODE, and one DATA-STACK segment named DATA. A 
SMALL subsystem named SUB2 contains one CODE! segment named 
SUB2_CODE, and one DATA-STACK segment named DATA. When the program 
modules are combined, all segments with the same name are combined. 

The memory layout of the loaded program containing the two subsystems SUB1 and 
SUB2 is as follows (it is assumed that both subsystems are SMALL RAM): 



CODE 
SUB1_CODE 



PROGRAM 
CODE 
OF 

SUBSYSTEM 
SUB1 



-CS 



CODE 
SUB2_CODE 



PROGRAM 
CODE 
OF 

SUBSYSTEM 
SUB2 



HIGH 



LOW 



SUB1 & SUB2 
PROGRAM 
STACK 



DATA 
SEGMENT 
SUB1 &SUB2 
PROGRAM 

DATA & 
CONSTANTS 



SS 
-DS 



Note that a program using the MEDIUM segmentation control is equivalent to a 
program in which each module is declared to be in a unique SMALL subsystem. 

A module belonging to a COMPACT subsystem takes the name of its CODE segment 
and the name of its DATA segment from the subsystem name. So a COMPACT 
subsystem named SUB1 contains one CODE segment named SUBl_CODE, one 
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DATA segment named SUB1_DATA, and one STACK segment named STACK. A 
COMPACT subsystem named SUB2 contains one CODE segment named 
SUB2_CODE, one DATA segment named SUB2_DATA, and one STACK segment 
named STACK. The loaded program will contain five segments, two CODE seg- 
ments, two DATA segments, and one STACK segment. Note that a program using the 
LARGE segmentation control is equivalent to a program in which each module is 
declared to be in a unique COMPACT subsystem. 

A LARGE subsystem can be simulated by a COMPACT subsystem containing only 
one module. However, LARGE subsystems are useful for the following reason. A 
LARGE subsystem named SUB1, which contains the modules MODI, MOD2, and 
MOD3, has three CODE segments named MODl_CODE, MOD2_CODE, and 
MOD3_CODE, and three DATA segments named MODl_DATA, MOD2_DATA, 
and MOD3_DATA. As usual, it contains one STACK segment named STACK. It is 
possible to use a LARGE subsystem instead of inventing names for many COMPACT 
subsystems, each containing only one module. Note that the segment name in the 
LARGE subsystem is derived from the module names and not from the subsystem 
name. 

PL/M-386 

For the 80386 microprocessor, the LARGE segmentation control is identical to the 
COMPACT segmentation control. However, there is a difference between LARGE 
and COMPACT subsystems. In a LARGE subsystem, the external definition of all 
symbols in the EXPORTS list have their segment field set to an unknown value. This 
enables the creation of external far objects with public locations that are unknown at 
compile time. In all other respects, a LARGE subsystem is identical to a COMPACT 
subsystem. 

end 

PL/M-386 

13.4.1 Open Subsystems 

Compiling files using only the segmentation controls and using no other subsystem 
controls produces open subsystems. When object modules are combined, all modules 
created from compilations specifying a particular segmentation control are automati- 
cally combined. Segments are created according to the rules for the segmentation 
control. A list of modules belonging to an open subsystem is therefore not needed at 
compile time. Modules can be freely added to or deleted from an open subsystem at 
any time during program development. 
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Note that both RAM and ROM modules are combined into the single open subsys- 
tem. For a SMALL subsystem, be careful when combining RAM and ROM modules, 
particularly concerning the passing of pointer parameters and the accessing of con- 
stants not in the current module. 

It is not possible to pass pointer parameters between SMALL RAM and SMALL 
ROM modules, because pointers are defined differently in each submodel. Also, it is 
not possible to directly reference constants defined in a ROM module from a RAM 
module, and vice versa, because RAM modules define constants to be in the data 
segment, and ROM modules define constants to be in the code segment. 

In the COMPACT model, passing pointer parameters between RAM and ROM mod- 
ules is not a problem, because pointers are always long. As in SMALL, the restric- 
tion on direct reference to constants applies. 

PL/M-386 

The names of the segments in both SMALL and COMPACT models are identical: 
CODE32 for the code segment, DATA for the data segment. This means that if 
SMALL and COMPACT modules are combined, they will also be combined to form 
a single open subsystem consisting of the CODE32, DATA, and STACK segments. 
Care must be taken regarding stack references, because COMPACT defines a sepa- 
rate stack segment and SMALL does not. For more information on 80386 micropro- 
cessor segment combining, see the binder chapter in the utilities user's guide. 

end 

PL/M-386 



13.4.2 Closed Subsystems 

A closed subsystem differs from an open subsystem in two ways: it has a name and it 
consists of a specific list of modules. The compiler must know the name of the 
subsystem and the modules belonging to the subsystem in order to create a closed 
subsystem. 

The need for a closed subsystem name is simply to differentiate a particular closed 
subsystem from another closed subsystem or from the open subsystem. This is done 
as follows: the name of the subsystem is added to the beginning of the segment names 
to create unique code and data segments. 

For example, if a subsystem is named PHASE1, then the code sections from all 
modules belonging to the PHASE 1 subsystem are combined into a single code 
segment called PHASE l_CODE32; similarly for COMPACT subsystems the data 
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sections are combined into a single data segment called PHASE 1_DATA. When us- 
ing COMPACT, however, the stack sections are still combined into a segment called 
STACK because only one execution-time stack is usually necessary. Using SMALL 
all data and stack segments are combined in one segment called DATA, as usual. 

A closed subsystem module list is needed for differentiation. For instance, if the 
compiler is not informed that module SCANNER belongs to subsystem PHASE 1, 
then the compiler has no choice but to assume that module SCANNER belongs to the 
open subsystem. 

Thus, every module in a program either is specified as part of a closed subsystem or, 
by default, becomes part of the open subsystem. A program can consist of only 
closed subsystems, or of both closed subsystems and the open subsystem, or of only 
the open subsystem (by default). There is only one open subsystem per program; all 
open subsystems are treated as one subsystem by the utility used to combine the 
program modules. 

13.4.3 Communication between Subsystems 

Within a subsystem there can be code and/or data items (procedures and variables) 
that must be known by other subsystems; that is, they are meant to be referenced 
from other subsystems. Such items are said to be exported. The export of a symbol is 
not directed at any one particular subsystem; it is directed at all subsystems in the 
program, including its own subsystem. 

It is important to realize that the subsystem definitions are additions to normal inter- 
module PUBLIC/EXTERNAL definitions, not replacements. 

For instance, module MODI belongs to subsystem SUB1 and makes a reference to 
symbol SYM2; SYM2 belongs to subsystem SUB2. SYM2 must be declared as 
EXTERNAL in MODI, as usual, and must also be declared as PUBLIC and ex- 
ported from SUB2. Using this information, the compiler generates an intersegment 
reference to SYM2. 

13.5 Syntax 

Defining subsystems means telling the compiler what extended segmentation model 
each subsystem uses, and which modules belong to each subsystem. In addition, it 
means telling the compiler which procedures and data are accessible from outside the 
subsystem. 
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Making everything available to all subsystems defeats the purpose of subsystems. For 
example, if a procedure is declared to be accessible from outside the subsystem, it is 
a far procedure. This means that all calls are far calls, even if the procedure is never 
actually accessed from outside its subsystem. 

Each subsystem in a PL/M program has one extended segmentation model definition, 
which takes one of the following forms: 

1 . $ model (subsystem-id [submodel] 



HAS module-list 
EXPORTS public-list 



f HAS module-list 
L L ' EXPORTS public-list 



2. $ model ( [submodel] 



HAS module-list 
EXPORTS public-list 



HAS module-list 
EXPORTS public-list J. 



3. $ model (submodel 



HAS module-list 
EXPORTS public-list 



HAS module-list 
EXPORTS public-list 



Where: 

model is SMALL, COMPACT, or LARGE and specifies the ex- 

tended segmentation model for the subsystem. All modules 
in the subsystem must be compiled with the same extended 
segmentation model. 

submodel is -CONST IN CODE- or -CONST IN DATA- and specifies 

the placement of constants. -CONST IN CODE- corresponds 
to the ROM submodel; -CONST IN DATA- corresponds to 
the RAM submodel. 

The default depends on the segmentation control and corres- 
ponds to the defaults of RAM/ROM for each model. The use 
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of the RAM and ROM controls (see Chapter 11) can create 
conflicts when subsystems are defined. RAM is specified by 
-CONST IN DATA-; ROM is specified by -CONST IN 
CODE-. 

subsystem-id is any PL/M identifier that can be used as a module name, 
and specifies the name of the subsystem. This ID does not 
conflict with any IDs used within the program. A subsystem 
control without subsystem-id defines the open subsystem. 

HAS module-list is a list of module names, separated by commas, specifying 
the modules belonging to the subsystem. These module 
names must exactly match the module names from each 
source file comprising the subsystem. (A module name is the 
name of the outermost DO block of a source file.) A particu- 
lar module name can appear in only one module-list. There 
are no default modules in the module-list. Any module for 
which a name does not appear in a module-list becomes part 
of the open subsystem. 

EXPORTS is a list of procedure, variable, and constant IDs, specifying 

public-list the code and data objects exported by the subsystem (i.e., 

accessible outside of the subsystem). Using a dollar sign ($) 
in a procedure name (within a subsystem definition) will 
cause an error. Any symbol in the exports list may be de- 
clared PUBLIC in at most one of the modules belonging to 
the subsystem, and should be declared EXTERNAL in all 
modules in and out of the subsystem that access the symbol. 

A particular exported symbol can appear in only one public- 
list. 

The public-list is exhaustive. Only the symbols in the public- 
list can be referenced from other subsystems. Symbols in the 
subsystem declared PUBLIC but not appearing in the public- 
list are accessible only from within the subsystem itself. Con- 
versely, PUBLIC symbols that are not intended to be 
referenced from outside the subsystem should not appear in 
the public-list. These symbols are called domestic symbols. 

In most applications of the subsystem controls, the HAS and EXPORTS lists will 
have several dozen entries apiece. To accommodate lists of this length, a subsystem 
control may be continued over more than one control line. (The continuation lines 
must be contiguous, and each must begin with a dollar sign ($) in the first column.) 
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Keep in mind that using a dollar sign in a procedure name within a subsystem defini- 
tion will cause an error. Also, note that any number of HAS and EXPORTS lists can 
appear in a control, in any order. This enables formatting of the subsystem specifica- 
tion so it can be easily read and maintained. 

Consider the following subsystem definition: 

$COMPACT(SUB_INPUT -CONST IN CODE- HAS mod_l-i mod_5-> mod_3i 
$ EXPORTS input) 

$SMALL(SUB_PROCESS HAS mod_Hi mod_5-, mod_b-, mod_7-, mod_fl) 
$COMPACT(SUB_OUTPUT HAS mod_1-, mod-ID n EXPORTS format-, output) 

This sample program contains three subsystems: SUB_ INPUT, SUB_PROCESS, 
and SUB_OUTPUT. SUB_JNPUT and SUB_OUTPUT use the COMPACT ex- 
tended segmentation model. SUB_PROCESS uses the SMALL extended segmenta- 
tion model. Constants are stored with the code in SUBJNPUT. The SUB_1NPUT 
subsystem contains the modules mod_l, mod_2, and mod_3, and exports one sym- 
bol, input. SUB_PROCESS contains modules 4 through 8. SUB__PROCESS contains 
the main program, as it must, since it is the only SMALL subsystem in the program 
(recall that when mixing SMALL with other models, the main program must be 
SMALL). For this reason it does not need to export any symbols. (A subsystem 
containing the main program can export symbols (for instance, global variables). But 
other subsystems MUST export at least one symbol, otherwise they are totally unac- 
cessible to the main program, and therefore useless to the program of which they are 
a part.) SUB_OUTPUT supplies two symbols called format and output. 

The preceding subsystem definition should appear in all 10 modules (mod_l through 
mod_10), even though not all the exported symbols are used by all subsystems. It is 
recommended that the subsystem definition be kept in an INCLUDE file, then in- 
cluded in each module compiled. This avoids any problems in maintaining consist- 
ency between the subsystem definitions of all source modules. 

Consider another example, this time containing an open subsystem. Start from an 
existing COMPACT program that does not use extended segmentation models, but 
whose code has grown too large. Assume that the following modules from the 
original program (ATTACH, OPEN, CLOSE, ERRORS, ALLOCATE, FREE) 
were compiled with the following segmentation control: 
$C0flPACT 

If the modules ALLOCATE and FREE are factored out from the original program, 
creating SUBSYS1, the subsystem definition is as follows: 
$C0r1PACT(SUBSYSl HAS ALLOCATE-, FREE) 
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Now, suppose that the modules remaining in the open subsystem reference entry 
points AllocBuff and FreeBuff in SUBSYS1. These must be exported from 
SUBSYS1 as follows: 

$C0!1PACT(SUBSYS1 HAS ALLOCATE-, FREE n 

$ EXPORTS AllocBuff-, FreeBuff) 

or 

$C0I"IPACT(SLIBSYS1 HAS ALLOCATED EXPORTS AllocBuff: 
$ HAS FREE i EXPORTS FreeBuff) 

The second form illustrates how multiple HAS and EXPORTS lists can be used to 
document the items exported from each module. 

If a routine in SUBSYS1 references the procedure FatalError in the module 
ERRORS, the definition of the open subsystem is as follows: 
^COMPACT (EXPORTS FatalError) 

No data structures need to be changed, because data reference values can be two 
bytes. All procedures except AllocBuff and FreeBuff use the short call and return 
mechanism. 

13.5.1 Placement of Segmentation Controls 

The segmentation controls have special restrictions associated with their placement. 
These rules are as follows: 

• The segmentation controls are primary controls. They must appear before the 
DO statement of the module name. 

• Only the definition of the open subsystem (with no submodel and no EXPORTS 
list) can be placed on the invocation line; definitions of all other subsystems must 
occur inside the source program. 

The subsystem definitions for the entire program can be included in the compilation 
of each module using the INCLUDE control. The compiler extracts the information 
needed to correctly and efficiently compile each module's intrasubsystem and inter- 
subsystem references. 

13.6 Exporting Procedures 

A symbol included in a subsystem's EXPORTS list must be declared PUBLIC in one 
of the modules in that subsystem. The symbol, called an exported symbol, can be 
referenced by modules in other subsystems. A PUBLIC symbol defined within a 
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subsystem but not listed in its EXPORTS list is called a domestic symbol. It should be 
referenced only by modules within the same subsystem. 

A procedure should be exported only if it must be referenced outside the defining 
subsystem, because accessing exported procedures will, in general, require more 
code and time than is required for domestic procedures. 

Exported procedures have the following characteristics: 

• The long form of call and return is used. 

• The caller's DS register (and the ES register for the 80386 microprocessor) is 
saved and restored upon entry and exit. 

• The DS register (and the ES register for the 80386 microprocessor) is loaded 
with the associated data segment upon entry. 

NOTE 

If a SMALL or MEDIUM module calls a procedure that is exported from a 
COMPACT or LARGE subsystem, the stack sections of the two will not be 
combined when the modules are combined because the segments contain- 
ing them have different names (see Chapter 11). To get the proper stack 
size, the SEGSIZE control on the utility used to combine the program 
modules must be used to increase the size of the DATA segment. This 
segment must be increased by the sum of the stack requirements for both 
the SMALL or MEDIUM module and the subsystem. 

The SMALL RAM segmentation control uses short pointers. Therefore, care must be 
taken when calling procedures that have pointer parameters and are exported from a 
SMALL subsystem. In these cases, the compiler always uses the value of the current 
DS register as the selector portion of the long pointer. This means that passing a 
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pointer to any data items declared in the SMALL module will produce the proper 
result, but the following restrictions must be observed for the special cases: 

1. If the actual parameter is the NIL pointer, DS:0 will be passed to the exported 
procedure. Consequently, the procedure executes differently if it is called from a 
SMALL module than if it had been called from a COMPACT, MEDIUM, or 
LARGE module. For example: 

^COMPACT (F00 HAS Ni EXPORTS F00) 

SSriALL 

n: DO; 

DECLARE PTR POINTER ; 

F00: PROCEDURE (P) EXTERNALS 
DECLARE P POINTERS 

END F00; 

CALL F00 (NIL); /* Wrong-, will pass DS:D */ 

PTR = NIL; 

CALL F00 (PTR); /* Wrong-, will pass DS:D */ 

end n; 

^COMPACT (F00 HAS N; EXPORTS F00) 
N : DO; 

F00: PROCEDURE (P) PUBLIC; 
DECLARE P POINTER; 
DECLARE B BYTE ; 

B = (P=NIL);/* Will assign FALSE (DDOH) to B 
if F00 is called from SHALL ; 
Will assign TRUE (QFFH) to B 
otherwise */ 

END F00; 

CALL F00 (NIL); /* Right-, will pass □ : */ 

END n; 
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2. If the actual parameter is a pointer to a procedure, the compiler extends the short 
pointer with DS and then passes the value of DS: (offset of procedure) to the 
exported procedure. This situation should be avoided because the result of any 
reference through such a pointer is undefined. For example: 

^COMPACT (F00 HAS NS EXPORTS F00) 

$SMALL 

H: DOS 

DECLARE PTR POINTER S 

DECLARE TABLE ( ID ) BYTE S 

F00: PROCEDURE (P) EXTERNALS 
DECLARE P POINTER S 

END FOOS 

BAZ: PROCEDURES 

END BAZS 

CALL F00 OBAZ)S 

PTR = 3BAZS 
CALL F00 (PTR)S 
CALL F00 (STABLE) S 



/* Urong n will pass */ 
/* DS:of f set-of-BAZ */ 

/* Urongn will pass DS:PTR */ 
/* Right n will pass pointer to TABLE */ 



END H =, 



13.6.1 Large Matrix Example 

The large REAL matrix example can now be fully developed (see Section 13.4). 
Recall that one module for each row is needed, with each module containing a 
1 -billion element REAL array. Running such an application is possible only on sys- 
tems having virtual memory management for supporting such large data. The first 
module could be: 

R0U0_I10D: DOS /* R0U0_M0D is the module name */ 

DECLARE ROUD (1DDDDDDDDD) REAL PUBLICS 
END R0WCLJ10DS 



PL/M-386 

I 
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The modules for ROW1 through ROW9 are similar. The subsystem definition at this 
point is: 



^COMPACT 


( 


Roun 


_SYS 


HAS 


Royo. 


_MOD =. 


r v/ n a n t r 

EXPORTS 


ROlilD 


) 


^COMPACT 


( 


ROIill. 


_SYS 


HAS 


Royi. 


_m o d ; 


EXPORTS 


ROIill 


) 


^COMPACT 


( 


ROW?. 


_SYS 


HAS 


row2. 


_mod; 


EXPORTS 


ROUS 


) 


^COMPACT 


< 


R0U3. 


_SYS 


HAS 


R0y3. 


_mod; 


EXPORTS 


R0W3 


) 


^COMPACT 


( 


R0U4. 


_SYS 


HAS 


rouh. 


_HODn 


EXPORTS 


ROWM 


) 


^COMPACT 


( 


ROWS. 


_SYS 


HAS 


Roys. 


_mod; 


EXPORTS 


ROUS 


) 


^COMPACT 


( 


ROUb. 


_SYS 


HAS 


Royt. 


_mod; 


EXPORTS 


ROU.fc. 


) 


^COMPACT 


( 


rouv. 


_SYS 


HAS 


Roy?. 


_mod; 


EXPORTS 


ROW? 


) 


^COMPACT 


( 


Roya. 


_SYS 


HAS 


ROUfl. 


_mod; 


EXPORTS 


ROIilfl 


) 


^COMPACT 


( 


Roy^. 


_SYS 


HAS 


Royi 


_MOD; 


EXPORTS 


ROLH 


) 



Now define the program: 
MATRIX—MOD : DO; 

DECLARE ROyQ (lOOOOOOOOQ) REAL EXTERNALS 

DECLARE ROyi ( 1DOODDOOOD ) REAL EXTERNALS 

DECLARE R0y5 ( 100DDDOOOO ) REAL EXTERNALS 

DECLARE R0U3 (10DOOOOOOD) REAL EXTERNALS 

DECLARE ROy^t (lOOOOODOOO) REAL EXTERNALS 

DECLARE ROUS ( ) REAL EXTERNALS 

DECLARE ROyb (1DOODDDDDO) REAL EXTERNALS 

DECLARE ROUT ( lOOOOODOOO ) REAL EXTERNAL ; 

DECLARE ROyfi (lOOOOODOOO) REAL EXTERNALS 

DECLARE ROyi (lOOOOODOOO ) REAL EXTERNAL; 

DECLARE ROy_POINTERS (10) POINTER INITIAL ( 

aRoyo-, aRoui-, 3R0U2-, brows-, aRouM-, 
aRoys-, aRoyb-, aRoy?-, aRoua-, aRoyi ); 

RETRIEVEELEMENT: PROCEDURE (ROWnCOL) REAL PUBLICS 

DECLARE (ROy.COL) U R D ; 

DECLARE ROyPTR POINTER-, 
ROy_ARR AY BASED ROy_PTR (1) REAL; 

ROU_PTR = ROU_POINTERS (ROU); 

RETURN ROU_ARR AY (COL); 
END RETRIEVE-ELEMENT; 

STORE—ELEMENT : PROCEDURE (ROU-iCOL-iVAL) PUBLIC; 

DECLARE (ROy.COL) UORD; 

DECLARE VAL REAL; 

DECLARE ROU_PTR POINTER-, 
ROU_ARRAY BASED ROU_PTR (1) REAL; 

ROU_PTR = ROU_POINTERS (ROU); 

ROy_ARRA Y (COL) = VAL; 
END STORE-ELEMENT; 

/* the matrix processing code inserted here */ 
END MATRIX— MOD ; 
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(continued) 

Now assume that other modules will be added to this program later. In this case, it is 
better to put MATRIX_MOD and these other modules in the COMPACT OPEN 
subsystem. This way modules can freely be added or deleted without having to rede- 
fine the overall subsystem structure. Also assume the need to calculate sines and 
cosines of various matrix elements. The functions SINE and COSINE are supplied in 
an external math package. The only thing known about this package is that all its 
routines require long calls. 



The final subsystem definition is now: 



5LARGE ( 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
^COMPACT 
$C0nPACT 



EXPORTS 

( R0WD_ 

( R0W1_ 

( ROWS- 

( R0W3_ 

( R0UM_ 

( R0W5_ 

( ROUk 

( R0W7_: 

( R0WA_: 

( R0UH_: 



SINE 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 

SYS HAS 



COSINE 
R0WD_ 
R0U1_ 
R0U2_ 
R0U3_ 
R0li)H_ 
ROUS^ 
R0Ub_l 
R0U7 
R0Wfl_l 
RObn 



) 

IIODi 

noDi 
noDi 
noDi 
noDi 
noDn 
mod^ 

HODn 
H0Dn 

noDn 



EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 
EXPORTS 



ROWD ) 

ROWl ) 

ROUS ) 

R0W3 ) 

R0W4 ) 

ROUS ) 

ROUb ) 

R0U7 ) 

ROUS ) 

ROUT ) 



The COMPACT control should appear in the invocation line. The first control line 
indicates that the symbols SINE and COSINE require long references and belong to 
some unknown subsystem. The next ten lines define the ten closed subsystems, each 
containing a row of the matrix. The COMPACT control is specified on the invocation 
line when compiling MATRIX_MOD (and when compiling any other module in the 
program except the ROW modules). 

Because every module in this program should be compiled with the same subsystem 
definitions, it is convenient to put these control lines in an INCLUDE file. If any 
changes to the subsystem definitions are made later, only one file needs to be 
updated. 

end 

— PL/M-386 
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ERROR AND 
WARNING MESSAGES 



The compiler may issue five varieties of error and warning messages: 

• PL/M program error messages 

• Fatal command tail and control error messages 

• Fatal input/output error messages 

• Fatal insufficient memory error messages 

• Fatal compiler failure error messages 

• Insufficient memory warning messages 

The source errors are reported in the program listing; the fatal errors are reported on 
the console device. 



14.1 PL/M Program Error and Warning Messages 

Nearly all of the source PL/M program error messages are interspersed in the listing 
at the point of error and follow the general format: 

***ERR0R mmm IN nnn (LINE ppp ) -, NEAR ' aaa' -, message 

or: 

***WARNING mmm IN nnn (LINE ppp)-. NEAR 'aaa'-, message 



Where: 
mmm 

nnn 

PPP 
aaa 



is the error number from the following list of source error 



is the source statement number where the error occurs, 
is the actual source line number where the error occurs, 
is the source text near where the error is detected. 



message is the error explanation from the following list of source error 

messages. 
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The following source error messages may be encountered. 

***ERR0R 1 INVALID CONTROL 

An unrecognized control in the control line; for example: 

SNXCODEi /* probably intended NOCODE */ 

***ERR0R S PRIMARY CONTROL FOLLOWS NON-CONTROL LINE 

Primary controls can appear as control lines in the source program, but they 
must come first. No other statements can precede them. 

***ERR0R 3 MISSING CONTROL PARAMETER 

Certain controls (e.g., INCLUDE), require the specification of a parameter. 

***ERR0R H INVALID CONTROL PARAMETER 

Examples are an illegal pathname for a control such as OBJECT or a string 
where a number is expected. 

***ERR0R 5 INVALID CONTROL FORMAT 

See Chapter 1 1 for correct formatting of control lines. Following is an example 
that could cause this error: 
$LIST CMYPROG.LST) n 

This error could occur because no pathname is expected on this control. It could 
also be caused if an INCLUDE was followed by another control on the same 
line. 

***ERR0R h 

Not used. 

***ERR0R 7 INVALID PATHNAME 

The pathname for a file has been incorrectly specified; see the host-system oper- 
ating instructions. 

***UARNING fi ILLEGAL PAGELENGTH-, IGNORED 

The pagelength specified is less than 5 or greater than 255; the default is 60. 

***ERR0R T ILLEGAL PAGEUIDTH -, IGNORED 

The pagewidth specified is less than 60 or more than 132; the default is 120. 

***UARNING 10 RESPECIFIED PRIMARY CONTROL-, IGNORED 

Primary controls can be specified only once and cannot alter a previous setting. 

***ERR0R 11 MISPLACED ELSE OR ELSEIF CONTROL 

ELSE or ELSEIF control occurred without being preceded by a corresponding 
IF control. 
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***ERROR IE MISPLACED ENDIF CONTROL 

ENDIF control occurred without being preceded by a corresponding IF control. 

***ERR0R 13 HISSING ENDIF CONTROL 

End of source file without an ENDIF control to match a previous IF. 

***ERR0R m NAME TOO LONG ( 31 ) n TRUNCATED 

Switch variable name in IF, ELSE, SET, or RESET statement is too long. 

***ERR0R IS HISSING OPERATOR 

Two operands in an expression must be separated by an arithmetic, logical, or 
relational operator. 

***WARNING lb INVALID CONSTANT-, ZERO ASSUMED 

The constant specified by SET, IF, or ELSEIF is invalid. 

***ERR0R 17 INVALID OPERAND 

SET, RESET, IF, or ELSEIF were used in an invalid position. 

***UARNING Ifl PARENTHESES IGNORED UITHIN CONDITIONAL 
COMPILATION CONDITION 

Parentheses within conditional compilation conditions are ignored and the ex- 
pression is evaluated according to the regular precedence rules. 

***ERR0R n LIMIT EXCEEDED: SAVE NESTING 

See Appendix B for the correct limit. 

***ERR0R ED LIMIT EXCEEDED: INCLUDE NESTING 

For example, a file named A is included, which includes a file named B, and so 
on. This error will occur when the limit is exceeded. See Appendix B for the 
correct limit. 

***ERR0R El MISPLACED RESTORE CONTROL 

RESTORE can work only if there has been a prior SAVE. 

***ERR0R EE UNEXPECTED END OF CONTROL 

A segmentation control was expecting a continuation line or a right paren- 
thesis. 

***ERR0R S3 SYMBOL EXISTS IN MORE THAN ONE HAS LIST 

A module name can occur in only one HAS list. 

***ERR0R ELI SUBSYSTEM ALREADY DEFINED 

The subsystem name has already been defined. 
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***ERROR ES CONFLICTING SEGMENTATION CONTROLS 

More than one segmentation control affecting the module being compiled was 
encountered. One common cause is specifying both -CONST IN CODE- and 
ROM in a module with a subsystem definition. 

***ERR0R Eb ILLEGAL PL/11 IDENTIFIER 

Identifier does not meet the rules for PL/M identifiers. Identifiers can be up to 3 1 
alphanumeric characters or the underscore. However, the first character must be 
alphabetic or the underscore. 

***ERR0R 5? PREDEFINED SWITCHES ARE NOT VALID BEFORE 
MODULE NAME 

Predefined switches can be used only after the first DO statement. 
Error 27 is not used by PL/M-386. 

***UARNING Eft INVALID PL/M CHARACTER-. IGNORED 

Look near the text flagged for an invalid character, or one that is inappropriate in 
context. Delete it or retype the statement. 

***UARNING ET UNPRINTABLE CHARACTER -i IGNORED 

Retype the line in question using valid characters. 

***ERR0R 30 STRING TOO LONG-, TRUNCATED 

Match the intended variable type with the length of the flagged item to obtain the 
correct maximum length. See Appendix B for the correct limit. 

***ERR0R 31 ILLEGAL CONSTANT TYPE 

A constant contains illegal characters. This might reflect missing operators (e.g., 
A = 4T instead of A = 4 + T). 

***ERR0R 3E INVALID CHARACTER IN CONSTANT 

For example, 107B and OABCD will cause this error because neither can be valid 
in any PL/M interpretation; 7 is not a binary numeral, B cannot occur in decimal 
or octal, and neither string ends in H. 
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***ERROR 33 RECURSIVE MACRO EXPANSION 

Following is an example causing this error: 

DECLARE A LITERALLY ' B ' i 
DECLARE B LITERALLY ' A' \ 



B = 4 =i /* error discovered here */ 

LITERALLYs cannot be declared circularly (i.e., solely in terms of each 
other). 

***ERR0R 34 LIMIT EXCEEDED: MACRO NESTING (S) 

This error occurs when too many DECLARE statements refer back through each 
other to the one that actually supplies a type. See Appendix B for the correct 
limit. For example: 

DECLARE A LITERALLY 'B'^ 
DECLARE B LITERALLY 'C*'i 



DECLARE Y LITERALLY 'Z'n 
DECLARE Z BYTE INITIAL (77); 



A=7; /* error discovered here */ 

***ERR0R 35 LIMIT EXCEEDED: SOURCE LINE LENGTH (ISA) 

See Appendix B for the correct limit. 

***ERR0R 3b 

Not used. 

***ERR0R 37 INVALID REAL CONSTANT 

***WARNING 3fl REAL CONSTANT UNDERFLOW 

An underflow occurred when conversion into floating-point was attempted. 

***WARNING 31 REAL CONSTANT OVERFLOW 

An overflow occurred when conversion into floating-point was attempted. 

***ERR0R 4D NULL STRING NOT ALLOWED 

Strings of length zero are not supported. 

***ERR0R 41 DELETED: "<to/cens>" 

The compiler deleted tokens while attempting to recover from a syntax error. 
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***ERROR M2 INSERTED: "<tokens>" 

The compiler inserted tokens while attempting to recover from a syntax error. 

***ERR0R M3 STATEMENTS FOLLOW MODULE END 

Statements follow the logical end-of-module. 

***ERR0R MM CONSTANT TOO LARGE 

A constant value (e.g., 999,999,999,999) is too large for the compiler. 

***WARNING 45 MISMATCHED BLOCK IDENTIFIER 

If a label is supplied in an END statement, the label must match the first un- 
matched DO statement above the END. Sometimes the error involves a module 
name confused with a procedure name. 

***ERR0R Mb DUPLICATE PROCEDURE NAME 

Procedure names must be unique. 

***ERR0R M? LIMIT EXCEEDED: PROCEDURES 

Too many procedures in this module. Break it into smaller modules. See Appen- 
dix B for the correct limit. 

***ERR0R Mfl DUPLICATE PARAMETER NAME 

A parameter must be declared exactly once. This message indicates that the 
flagged parameter already has a definition at this block level, as in: 

YAR: PROCEDURE (YAR77-, Y AR7fl ) i 
DECLARE YAR77 BYTE i 
DECLARE YAR77 BYTE; 

Perhaps a different spelling was intended. 

***ERR0R MT NOT AT MODULE LEVEL 

The flagged attribute or initialization can be valid only at the module level, not in 
a procedure. 

***ERR0R SO DUPLICATE ATTRIBUTE 

Attributes should be specified only once. This message means the compiler has 
found a declaration like: 

DECLARE B BYTE EXTERNAL EXTERNAL; 

***ERR0R SI MISSING OR ILLEGAL INTERRUPT VALUE 

Interrupt numbers must be whole-number constants between and 255. Thus -7 
or 272 would be invalid. 

***ERR0R 52 INTERRUPT WITH PARAMETERS 

No parameters can be used in interrupt procedures. 
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***ERROR S3 INTERRUPT WITH TYPED PROCEDURE 

Interrupt procedures must be untyped. 

***ERR0R SM INVALID DIMENSION 

***ERR0R 55 LIMIT EXCEEDED: NESTED STRUCTURES 

See Appendix B for the correct limit. 

***ERR0R 5b STAR DIMENSION WITH STRUCTURE MEMBER 

Star dimension (*) must not be used with structures. The dimensions for an array 
that is a structure member must be specified explicitly. 

***ERR0R 57 CONFLICT WITH PARAMETER 

Object cannot be a parameter. 

***ERR0R Sfi DUPLICATE DECLARATION 

The flagged item already has a definition declared at this block level. 

***ERR0R ST ILLEGAL PARAMETER TYPE 

Parameters cannot be declared of type structure or array. 

***ERR0R bO DUPLICATE LABEL 

Each label must be unique within its block or scope. Otherwise, GOTOs and 
CALLs would have ambiguous targets. 

***ERR0R tl DUPLICATE MEMBER NAME 

Member has been declared twice in the same structure. For example, in: 

DECLARE AIR STRUCTURE (F4 BYTE-, FM BYTE); 
subsequent references to AIR.F4 would be ambiguous. 

***ERR0R UNDECLARED PARAMETER 

A parameter named in the procedure statement was not defined in the body of the 
procedure. 

***ERR0R b3 CONFLICTING ATTRIBUTES 

A variable has been declared with inconsistent attributes (e.g., PUBLIC or 
EXTERNAL, DATA or INITIAL, AT or BASED). 

***ERR0R LM LIMIT EXCEEDED : DO BLOCKS 

See Appendix B for the correct limit. 

***ERR0R LS ILLEGAL PARAMETER ATTRIBUTE 

Certain attributes cannot be used to declare a parameter (e.g., PUBLIC, 
EXTERNAL, DATA, INITIAL, AT, or BASED). 
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***ERROR bb UNDEFINED BASE 

A variable was declared BASED using an undeclared identifier. 

***ERROR b7 INVALID TYPE OR ATTRIBUTE FOR BASE 

A base must be a non-subscripted scalar of type ADDRESS, POINTER, WORD, 
SELECTOR, or OFFSET (PL/M-386 only). 

***ERR0R bfl MISPLACED DECLARATION 

Declarations and procedures can be interspersed, but not declarations and exe- 
cutable statements. 

***ERR0R INVALID BASE WITH LABEL OR MACRO 

BASED cannot be used with LABEL or LITERALLY types. 

***ERR0R 70 INVALID DIMENSION WITH LABEL OR MACRO 

LABEL or LITERALLY cannot be dimensioned. 

***EIRR0R 71 INITIALIZATION LIST REQUIRED 

A list of initial values is required if the INITIAL attribute, the non-external * 
dimension form, or the non-external DATA attribute is used. 

***ERR0R 72 BASED CONFLICTS WITH ATTRIBUTES 

Examples of attributes conflicting with base include AT, DATA, INITIAL, 
PUBLIC, and EXTERNAL. 

***ERR0R 73 DATA OR EXECUTABLE STATEMENTS IN 
EXTERNAL 

An EXTERNAL procedure, being defined elsewhere, cannot contain executable 
statements or data declarations for variables that are not formal parameters. 

***ERR0R 7M MISSING RETURN FOR TYPED PROCEDURE 

A typed procedure must return a value; thus, it must include a RETURN 
statement. 

***ERR0R 75 INVALID NESTED REENTRANT PROCEDURE 

Reentrant procedures cannot contain procedures. 

***ERR0R 7b LIMIT EXCEEDED: FACTORED LIST 

Too many variables were named in a factored declaration. Break it into several 
declarations. See Appendix B for the correct value. 

***ERR0R 77 LIMIT EXCEEDED: STRUCTURE MEMBERS 

See Appendix B for the correct value. 

***ERR0R 7fl MISSING PROCEDURE NAME 

Every procedure must have a name. 
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***ERROR MULTIPLE PROCEDURE LABELS 

Procedures must have only one name. 



***ERR0R SO DECLARATIONS HAY NOT BE LABELED 

Labels cannot be used on declaration statements. 



***ERR0R fll STAR DIM WITH FACTORED LIST NOT ALLOWED 

Separate the array declarations giving the data initializations for each array sepa- 
rately, or explicitly state the dimensions of the factored array declarations as in 
the following examples: 

DECLARE (AiB) (*) BYTE DATA ('abed'-, 'xywz'M /* is illegal */ 
DECLARE (A) (*) BYTE DATA ('abed'); /* is legal */ 

DECLARE (B)(*) BYTE DATA ('xywzTn /* is legal */ 

or 

DECLARE ( A i B ) ( H ) BYTE DATA ('abed', 'xywz')^ /* is legal */ 

***ERR0R A2 SIZE EXCEEDS nn BYTES 

Storage for the declared item exceeds the maximum storage for the microproces- 
sor. For the 8086 and the 80286 microprocessors, nn is 64K. For the 80386 
microprocessor, nn is 4G. 

***WARNING A3 PROCEDURE CONTAINS NO EXECUTABLE 
STATEMENTS 

This procedure does nothing, but executes successfully. 



***ERR0R AM 

Not used. 



***ERR0R fl5 INITIAL USED WITH ROM OPTION 

Variables declared with INITIAL are not initialized until load-time. Thus, if the 
program is in ROM, these initializations will never occur. 

***ERR0R fib LIMIT EXCEEDED: NUMBER OF PARAMETERS 

The procedure declaration includes too many parameters. See Appendix B for 
the correct limit. 



***ERR0R A7 

Not used. 

***ERR0R flfl LIMIT EXCEEDED: PROGRAM TOO COMPLEX 

The program has too many complex expressions, cases, or procedures. Break it 
into smaller procedures. 
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***ERR0R fll COMPILER ERROR: BAD ERROR RECOVERY 

An unrecoverable error occurred. Trying a different copy of the compiler on a 
different drive might reveal that the first copy had been damaged. Contact your 
Intel representative. 

***ERR0R TO COMPILER ERROR: MULTIPLE PARSE ARCS 

See source error message number 89. 

***ERR0R LIMIT EXCEEDED : PROGRAM TOO COMPLEX 

The program has too many complex expressions, cases, or procedures. Break it 
into smaller procedures. 

***ERR0R IE COMPILER ERROR: PARSE ARG STACK UNDERFLOW 

See source error message number 89. 

***ERR0R =13 LIMIT EXCEEDED: PROGRAM TOO COMPLEX 

The program has too many complex expressions, cases, or procedures. Break it 
into smaller modules. 

***ERR0R COMPILER ERROR: PARSE STACK UNDERFLOW 

See source error message number 89. 

***ERR0R IS COMPILER ERROR: PARSE BUFFER OVERFLOW 

See source error message number 89. 

***ERR0R lb LIMIT EXCEEDED: BLOCK NESTING 

The program has too many nested DO blocks. Break it into smaller procedures. 
See Appendix B for the correct limit. 

***ERR0R T7 COMPILER ERROR: SCOPE STACK UNDERFLOW 

See source error message number 89. 

***ERR0R Tfl LIMIT EXCEEDED: STATEMENT TOO COMPLEX 

The statement is too large for the compiler. Break it into several smaller 
statements. 

***ERR0R ^ COMPILER ERROR: SEMANTIC UNDERFLOW 

See source error message number 89. 

***ERR0R 1D0 STRING CONSTANT TOO LONG 

String constants used as scalars have a maximum of four characters. 

***ERR0R 1D1 UNSUBSCRIPTED ARRAY 

The array reference requires a subscript. 
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***li)ARNING 102 UNQUALIFIED STRUCTURE 

This statement is ambiguous as to which structure or member it references. 

***ERR0R 103 NOT AN ARRAY 

Subscripts are permitted only on identifiers declared as arrays. Check spelling 
consistency. 

***ERR0R 10M MULTIPLE SUBSCRIPTS 

PL/M has only single dimension arrays. Therefore, only one subscript is permit- 
ted in an array reference. For example, for any array TING references of the 
form TING(2,4) or TING(3,7,9,6) are invalid. 

***ERR0R 105 NOT A STRUCTURE 

For example, a reference of the form GNU.F1 , where GNU was not declared a 
structure. 

***ERR0R 10b UNDEFINED IDENTIFIER 

Every identifier must be declared. 

***ERR0R 107 UNDEFINED MEMBER 

For example, KAPI.HORN, where KAPI is a valid, declared structure but 
HORN is an undeclared member of the structure. 

***ERR0R IDA ILLEGAL ITERATIVE DO INDEX TYPE 

Only expressions of type BYTE, WORD, and INTEGER can be used. 

***ERR0R 101 UNDEFINED OR NOT A LABEL 

The identifier following GOTO must be a label; the flagged item was declared 
otherwise, or the identifier was declared as a label but was not defined. 

***ERR0R 110 MISSING RETURN VALUE 

A typed procedure must return a value that is specified by its RETURN 
statement. 

***ERR0R 111 INVALID RETURN WITH UNTYPED PROCEDURE 

An untyped procedure does not return a value; thus, its RETURN statement 
cannot specify one. 

***ERR0R IIS INVALID INDIRECT TYPE 

Only WORD or POINTER scalars can be used for indirect calls. This excludes 
WORD or POINTER expressions, BYTE, DWORD, INTEGER, or REAL 
scalars, all structures, and all arrays. 

***ERR0R 113 INVALID PARAMETER COUNT 

The number of actual parameters supplied in a CALL must be equal to the 
number of formal parameters declared in the procedure. 
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***ERROR im QUALIFIED PROCEDURE NAME 

Procedure names cannot be qualified. 



***ERR0R IIS INVALID FUNCTION REFERENCE 

Typed procedures can be invoked only by use in an expression, not by a CALL. 

***ERR0R lib INVALID CASE EXPRESSION TYPE 

Case expressions must be of type BYTE, WORD, or INTEGER. 

For PL/M-86 and PL/M-286, error 117 displays the following message: 
***ERR0R 117 LIMIT EXCEEDED: NUMBER OF CASES 

See Appendix B for the correct limit. 

For PL/M-386, error 117 displays the following message: 

***ERR0R 117 LIMIT EXCEEDED: NUMBER OF ACTIVE CASES 

Reduce the number of cases in this case statement; the maximum number has 
been exceeded. 

***ERR0R llfi TYPE CONFLICT 

An example of type conflict is WORD and REAL mixed in a reference. 

***ERR0R in INVALID BUILT-IN REFERENCE 

Built-in reference was qualified with a member name, or OUTPUT/OUTWORD 
did not appear on the left side of an assignment. 

***ERR0R 1E0 INVALID PROCEDURE REFERENCE 

Untyped procedures must be invoked by a CALL statement; references to such 
procedures are not permitted in expressions. 

***ERR0R 121 INVALID LEFT-HAND SIDE OF ASSIGNMENT 

The left-hand side of the assignment must be a scalar variable. For example, 
PROCEDURE = 4 or INWORD(7) = 9. 

***ERR0R 1EE INVALID REFERENCE 

Invalid label reference. 

***ERR0R 1E3 USE OF •»..- MAY BE UNSAFE 

The "dot" operator does not always produce correct results in a PL/M program 
that contains more than one data segment or more than one code segment. 

***ERR0R 1EM PROCEDURE NAME REQUIRED 

Procedure name is required for SET$INTERRUPT and INTERRUPT$PTR 
built-ins. 

For PL/M-286 and PL/M-386, error 124 is not used. 
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***ERROR 125 PROCEDURE NAME ONLY 

Parameters are not allowed on the procedure name in SET$INTERRUPT and 
INTERRUPT$PTR. 

For PL/M-286 and PL/M-386, error 125 is not used. 

For PL/M-86, error 126 displays the following message: 
***ERR0R 12b BAD INTERRUPT NUMBER (<=255) 

For PL/M-386, error 126 displays the following message: 
***ERR0R 12b BAD INTERRUPT NUMBER 

Interrupt numbers in a CAUSE$INTERRUPT statement must be whole-number 

constants in the range (0 - 255). 

For PL/M-286, error 126 is not used. 

***ERR0R 127 CONSTANT ONLY 

In this instance, a constant is required. 

***ERR0R 12A ARRAY REQUIRED 

Some built-ins need an array name as a parameter. 

***ERR0R 121 INTERRUPT PROCEDURE REQUIRED 

The name declared in a SET$INTERRUPT procedure or INTERRUPT$PTR 
function must be a previously declared procedure. 

For PL/M-286 and PL/M-386, error 129 is not used. 

***ERR0R 130 INVALID RESTRICTED OPERAND 

Illegal use of a dot operator. 

***ERR0R 131 INVALID RESTRICTED OPERATOR 

Only + and - can be used in restricted expressions. 

***ERR0R 132 

Not used. 

***ERR0R 133 REFERENCE REQUIRED 

A variable reference is required for LENGTH, LAST, and SIZE. 

***ERR0R 13M VARIABLE REQUIRED 

The operand to LENGTH, LAST, and SIZE must be a variable. 

***ERR0R 13S VALUE TOO LARGE 

A value is too large for its contextually determined type. 
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***ERROR 13b ABSOLUTE POINTER WITH SHORT POINTERS 

Two possible causes in the SMALL (RAM) case: pointer variables cannot be 
initialized with or assigned whole number constants, or the @ operator cannot be 
used with a variable that was located at an absolute address that was specified by 
a whole number constant. 

***ERR0R 137 INVALID RESTRICTED EXPRESSION 

Only addresses or constant types can be used in restricted expressions. 

***ERR0R 13 fl PUBLIC AT EXTERNAL 

PUBLIC declarations must be fully defined within the procedure. For example: 

DECLARE DARTH BYTE EXTERNAL i 

DECLARE VADER BYTE PUBLIC AT ( . DARTH ) '-, 

is illegal. 

***ERR0R 131 PUBLIC AT ABSOLUTE 

Absolute locations for PUBLICS are supported only under the LARGE option. 

For PL/M-286 and PL/M-386, error 139 is not used. 

***ERR0R 1M0 PUBLIC AT MEMORY 

PUBLIC at @ MEMORY is not supported by SMALL. 

For PL/M-286 and PL/M-386, error 140 is not used. 

***ERR0R mi AT BASED VARIABLE 

Based variables cannot be used in AT clauses. 

***ERR0R ma ILLEGAL FORWARD REFERENCE 

An AT expression cannot have a forward reference. Any location reference in the 
AT expression must refer to previously declared variables. 

***ERR0R 143 VARIABLE TYPE REQUIRED IN AN AT EXPRESSION 

The AT expression must be a variable name. For example: 

DECLARE B BYTE AT ( . proc_name ) i 
is illegal. 

***ERR0R 111 LIMIT EXCEEDED: DATA OR STACK SEGMENT 
TOO LARGE 

See Appendix B for the correct limit. 

***ERR0R mS LIMIT EXCEEDED: CODE OR CONST SEGMENT 
TOO LARGE 

See Appendix B for the correct limit. 
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***ERROR 14b LIMIT EXCEEDED: NUMBER OF EXTERNALS 

See Appendix B for the correct limit. 



***ERR0R 147 LABEL NOT AT LOCAL OR MODULE LEVEL 

Label was not used correctly. 

***ERR0R 14fl INITIALIZING MORE SPACE THAN DECLARED 

The number of initialization values exceeds the number of declared elements. 

***ERR0R 141 ILLEGAL MODULE NAME REFERENCE 

Module names cannot be referenced. 

***UARNING ISO USE OF "." WITH FAR PROCEDURE 

A subsequent indirect call made through the respective address/pointer generates 
the wrong type of call. 

***UARNING 1S1 USE OF "3" UITH NEAR PROCEDURE 

See source error message number 150. 

***ERR0R 152 INVALID OR "ST OPERAND 

Must be used with a variable, procedure, or constant list. 

***ERR0R 1S3 INVALID RETURN IN MAIN PROGRAM 

A main program must have no returns. 

***ERR0R 154 STAR DIMENSIONED VARIABLE UITH LENGTH-, 
SIZE OR LAST 

The LENGTH, LAST, and SIZE built-in functions cannot be used with variables 
declared with the implicit dimension specifier (*) and the EXTERNAL 
attribute. 

***ERR0R 155 SYMBOL EXPORTED FROM ANOTHER SUBSYSTEM 

A PUBLIC symbol in this module is also exported by another subsystem. 

***ERR0R 15b LONG POINTER REQUIRED FOR THIS 
CONSTRUCT 

A model with long pointers is required. 

***ERR0R 157 

Not used. 

***ERR0R 156 INITIALIZATION CONFLICTS WITH 
ATTRIBUTES 

An external variable cannot be initialized. 
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***ERROR 1ST ILLEGAL INTERRUPT PROCEDURE REFERENCE 

An interrupt procedure cannot be invoked with the CALL statement. 

For PL/M-86, error 159 is not used. 

***ERR0R IbO INTERRUPT PROCEDURES MUST BE PUBLIC 

An interrupt procedure must also be given the PUBLIC attribute. 

***ERR0R Ibl ILLEGAL ABSOLUTE POINTER OR SELECTOR 

Constants cannot be assigned to POINTERS or SELECTORS, nor used to 
initialize them. POINTERS and SELECTORS also cannot be passed as actual 
parameters. 

For PL/M-86, error 161 is not used. 

***ERR0R IbS LIMIT EXCEEDED: STATEMENT TOO COMPLEX 

The statement is too large for the compiler. Break it into several smaller 
statements. 

***UARNING IbE LIMIT EXCEEDED: PROGRAM COMPLEXITY 

Too many complex expressions, cases, etc. Break it into smaller procedures. 

For PL/M-86 and PL/M-286, error 162 is not used. 

***ERR0R lb3 COMPILER ERROR: SEMANTIC UNDERFLOW 

See source error message number 89. 

***ERR0R lb I COMPILER ERROR: INVALID NODE 

See source error message number 89. 

***ERR0R IbS: Eflb INTERFACE OBJECT NOT EXTERNAL 

If the machine parameter is 286, all identifiers in the id list must be declared 
EXTERNAL. 

For PL/M-286, error 165 is not used. 

***ERR0R Ibb COMPILER ERROR: INVALID TREE 

See source error message number 89. 

***ERR0R lb? COMPILER ERROR: SCOPE STACK UNDERFLOW 

See source error message number 89. 

For PL/M-86 and PL/M-286, error 168 displays the following message: 
***ERR0R Ibfl LIMIT EXCEEDED: BLOCK NESTING 

See Appendix B for the correct limit. 
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For PL/M-386, error 168 displays the following message: 
***ERR0R Ibfl LIMIT EXCEEDED: PROGRAM COMPLEXITY 

The program has too many complex expressions, cases, or procedures. Break it 
into smaller procedures. 

***ERR0R Ibl COMPILER ERROR: INVALID RECORD 

See source error message number 89. 

For PL/M-86 and PL/M-286, error 169 is not used. 

***ERR0R 170 INVALID DO CASE BLOCK-, AT LEAST ONE 
CASE REQUIRED 

The DO CASE block is described in Section 6.1. 

***ERR0R 171 LIMIT EXCEEDED: NUMBER OF CASES 

See Appendix B for the correct limit. 

***ERR0R 17S LIMIT EXCEEDED: NESTING OF TYPED 
PROCEDURE CALLS 

See Appendix B for the correct limit. 

***ERR0R 173 LIMIT EXCEEDED: NUMBER OF ACTIVE 
PROCEDURES AND DO CASE GROUPS 

See Appendix B for the correct limit. 

***ERR0R 17M ILLEGAL NESTING OF BLOCKS-, ENDS NOT 
BALANCED 

For every DO, an END is needed. 

***ERR0R 17S COMPILER ERROR: INVALID OPERATION 

See source error message number 89. 

***ERR0R 17b LIMIT EXCEEDED: REAL EXPRESSION 
COMPLEXITY 

The REAL stack has eight registers. Heavily nested use of REAL functions 
with REAL expressions as parameters can get excessively complex. See 
Appendix F. 

***ERR0R 177 COMPILER ERROR: REAL STACK UNDERFLOW 

See source error message numbers 89 and 176. 

***ERR0R 17A LIMIT EXCEEDED: BASIC BLOCK 
COMPLEXITY 

There is a very long list of statements without labels, CASEs, IFs, GOTOs, and/ 
or RETURNs. Either break the procedure into several smaller procedures, or 
add labels to some of the statements. 
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***ERROR 171 LIMIT EXCEEDED: STATEMENT SIZE 

The statement is too large for the compiler. Break it into several smaller 
statements. 

***ERR0R m LIMIT EXCEEDED: PROCEDURE COMPLEXITY 
FOR OPTIMIZE (2) 

The combined complexity of statements, user labels, and compiler-generated 
labels is too great. Simplify as much as possible, perhaps breaking the procedure 
into several smaller procedures. 

***ERR0R 200 ILLEGAL INITIALIZATION OF MORE SPACE 
THAN DECLARED 

The number of initialization values exceeds the number of declared elements. 

***ERR0R 201 INVALID LABEL: UNDEFINED 

No definition for this label was found. 

***ERR0R 202 LIMIT EXCEEDED: NUMBER OF EXTERNAL ITEMS 

See Appendix B for the correct limit. 

For PL/M-86 and PL/M-286, error 202 is not used. 

***ERR0R 203 COMPILER ERROR: BAD LABEL ADDRESS 

See source error message number 89. 

***ERR0R 20M LIMIT EXCEEDED: CODE SEGMENT SIZE 

See Appendix B for the correct limit. 

***ERR0R 205 COMPILER ERROR: BAD CODE GENERATED 

See source error message number 89. 

***ERR0R 20L- LIMIT EXCEEDED: DATA SEGMENT SIZE 

See Appendix B for the correct limit. 

***ERR0R 207 ATTEMPT TO USE AS DIVISOR IN 
DIVISION/MODULO 

Zero cannot be used as a divisor in division/modulo; use 1 . This error appears at 
the end as a semantic error. 

***ERR0R 210 COMPILER ERROR: OBJECT MODULE 
GENERATION ERROR 

See source error message number 89. 

For PL/M-86, error 210 is not used. 
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***ERROR Ell COMPILER ERROR: DEBUG SEGMENT SIZE 
OVERFLOW 

See source error message number 89. 
For PL/M-86, error 21 1 is not used. 

***ERR0R E1E COMPILER ERROR: ILLEGAL FIXUP 

See source error message number 89. 

For PL/M-86, error 212 is not used. 

***ERR0R E30 COMPILER ERROR: INVALID INTERNAL TYPE 

See source error message number 89. 

***ERR0R Em] NO DEBUG INFORMATION FOR VARIABLES 
BASED ON BASED VARIABLES 

Debug information is available only for the first level of indirection. 

***ERR0R E41 ILLEGAL TYPE CASTING 

For example: 

pt E =pointer (real_value) 
is illegal. 

***ERR0R E4E TRUNCATION OF n BIT OFFSET 

OFFSET was assigned to a variable with a size less than 32 bits; the assigned 
value may not be a valid OFFSET. For the 8086 and 80286 microprocessors, n is 
16. For the 80386 microprocessor, n is 32. 

For PL/M-86 and PL/M-286, error 243 displays the following message: 
***ERR0R EH3 ILLEGAL INITIALIZATION WITH 

CONSTANT: USE NIL 

Use NIL to initialize POINTER to zero. 

For PL/M-386, error 243 displays the following message: 

***ERR0R EH3 Efib INTERFACE OBJECT NOT EXTERNAL 

If the machine parameter is 286, all identifiers in the id list must be declared 
EXTERNAL. 

***ERR0R Em SYMBOL REPEATED IN INTERFACE 
SPECIFICATION 

Symbols can only be used once in an INTERFACE control (i.e. , a symbol cannot 
be repeated in the INTERFACE control). 

For PL/M-86 and PL/M-286, error 244 is not used. 
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***ERROR E1S AT VARIABLE IN DIFFERENT SEGMENT 

A variable cannot be declared using both the DATA attribute and the AT attribute 
when using the ROM option. DATA should be in CODE segments and INITIAL 
should be in DATA segments. 

For PL/M-386, error 245 is not used. 

***WARNING E17 INDIRECT CALL THROUGH lb BIT VARIABLE 

An indirect call through a 16-bit variable is not recommended because a 16-bit 
variable can address only the first 64K of a segment. 

For PL/M-86 and PL/M-286, warning 247 is not used. 

***WARNING E4fl BASE TYPE HAS ONLY lb BITS OFFSET 

Use of a 16-bit base specifier is not recommended because it can address only the 
first 64K of a segment. 

For PL/M-86 and PL/M-286, warning 248 is not used. 

***ERR0R ESI COMPILER ERROR: INVALID OBJECT 

See source error message number 89. 

***ERR0R E5E COMPILER ERROR: SELF NAME LINK 

See source error message number 89. 

***ERR0R 253 COMPILER ERROR: SELF ATTR LINK 

See source error message number 89. 

***ERR0R ESM LIMIT EXCEEDED : PROGRAM COMPLEXITY 

The program has too many complex expressions, cases, or procedures. Break it 
into smaller modules. 

***ERR0R ESS LIMIT EXCEEDED: SYMBOLS 

See Appendix B for the correct limit. 

NOTE 

If a terminal error is encountered, program text beyond the point of error is 
not compiled. A terminal error message will appear at the point of error in 
the program listing. 
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14.2 Fatal Command Tail and Control Error Messages 



Fatal command tail errors are caused by an improperly specified compiler invocation 
command or an improper control. The errors that can occur are as follows: 

COMMAND TAIL TOO LONG 

COriPl AND TAIL BUFFER LIMIT EXCEEDED AT OR NEAR: xxx 

ILLEGAL COMMAND TAIL SYNTAX OR VALUE 

UNABLE TO PARSE COMMAND TAIL AT OR NEAR: xxx 

ILLEGAL COMMAND TAIL SYNTAX OR VALUE 

UNRECOGNIZED CONTROL IN COMMAND TAIL 

INVOCATION COMMAND DOES NOT END WITH <hl> 

ILLEGAL COMMAND TAIL SYNTAX 



14.3 Fatal Input/Output Error Messages 

Fatal input/output errors occur when the user incorrectly specifies a pathname for 
compiler input or output. These error messages are of the form: 

PL/M-xxx ERROR - 

FILE: 

NAME: 

ERROR: 

COMPILATION TERMINATED 



These errors also occur when the device runs out of space (e.g., the list file is larger 
than the available memory). 



14.4 Fatal Insufficient Memory Error Messages 

The fatal insufficient memory errors are caused by a system configuration with insuf- 
ficient RAM memory to support the compiler. 

The errors that can occur due to insufficient memory are as follows: 

NOT ENOUGH MEMORY FOR COMPILATION 

DYNAMIC STORAGE OVERFLOW 

NOT ENOUGH MEMORY FOR CODE GENERATION 

For PL/M-86 and PL/M-286, the following message can also occur: 
NOT ENOUGH MEMORY FOR FINAL ASSEMBLY 
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14.5 Fatal Compiler Failure Error Messages 



The fatal compiler failure errors are internal errors that should never occur. If you 
encounter such an error, please contact your Intel representative. The errors falling 
into this class are as follows: 



***ERR0R fll COMPILER ERROR: 
***ERR0R TO COMPILER ERROR: 
***ERR0R IE COMPILER ERROR: 
***ERR0R «m COMPILER ERROR 
***ERR0R TS COMPILER ERROR 
***ERR0R T? COMPILER ERROR 
***ERR0R TT COMPILER ERROR 
***ERR0R lb3 COMPILER ERROR 
***ERR0R lb4 COMPILER ERROR 
***ERR0R Ibfc, COMPILER ERROR 
***ERR0R 1L7 COMPILER ERROR 
***ERR0R 175 COMPILER ERROR 
***ERR0R 177 COMPILER ERROR 
***ERR0R 203 COMPILER ERROR 
***ERR0R EOS COMPILER ERROR 
***ERR0R E10 COMPILER ERROR 
GENERATION 

For PL/M-86, error 210 is not used. 



BAD ERROR RECOVERY 
MULTIPLE PARSE ARCS 
PARSE ARG STACK UNDERFLOW 
PARSE STACK UNDERFLOW 
PARSE BUFFER OVERFLOW 
SCOPE STACK UNDERFLOW 
SEMANTIC UNDERFLOW 
SEMANTIC UNDERFLOW 
INVALID NODE 
INVALID TREE 
SCOPE STACK UNDERFLOW 
INVALID OPERATION 
REAL STACK UNDERFLOW 
BAD LABEL ADDRESS 
BAD CODE GENERATED 
OBJECT MODULE 



***ERROR Ell COMPILER ERROR: DEBUG SEGMENT SIZE 
OVERFLOW 

***ERROR E1E COMPILER ERROR: ILLEGAL FIXUP 

For PL/M-86, error 212 is not used. 



***ERROR E3D COMPILER ERROR: 

For PL/M-86, error 230 is not used. 



INVALID INTERNAL TYPE 



***ERROR ESI COMPILER ERROR: 
***ERROR ESE COMPILER ERROR: 
***ERROR ES3 COMPILER ERROR: 



INVALID OBJECT 
SELF NAME LINK 
SELF ATTR LINK 



It is also possible to receive an UNKNOWN FATAL ERROR message. 
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14.6 Insufficient Memory Warning Messages 

The following warnings may occur if there are too many symbols for symbol 
processing: 

NOT ENOUGH MEMORY FOR FULL DICTIONARY LISTING 
NOT ENOUGH MEMORY FOR ANY XREF PROCESSING 
NOT ENOUGH MEMORY FOR FULL XREF PROCESSING 
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PL/M RESERVED WORDS AND 
PREDECLARED IDENTIFIERS 

These are reserved words in PL/M-86, PL/M-286 and PL/M-386. They cannot be 
used as identifiers. 



ADDRESS 


INTEGER 


AND 


INTERRUPT 


AT 


LABEL 


BASED 


LITERALLY 


BY 


MINUS 


BYTE 


MOD 


CALL 


NOT 


CASE 


OR 


DATA 


PLUS 


DECLARE 


POINTER 


DISABLE 


PROCEDURE 


DO 


PUBLIC 


DWORD 


REAL 


ELSE 


REENTRANT 


ENABLE 


RETURN 


END 


SELECTOR 


EOF 


STRUCTURE 


EXTERNAL 


THEN 


GO 


TO 


GOTO 


WHILE 


HALT 


WORD 


IF 


XOR 


INITIAL 






Additionally, the following are reserved words in PL/M-386. 

CHARINT OFFSET 
HWORD QWORD 
LONGINT SHORTINT 
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The following are identifiers for PL/M-86/286/386 built-in procedures and prede- 
clared variables. If one of these identifiers is declared in a DECLARE statement, the 
corresponding built-in procedure or predeclared variable becomes unavailable within 
the scope of the declaration. 



ABS 


MOVRW 


ADJUSTRPL 


MOVW 


BLOCKINPUT 


NIL 


BLOCKINWORD 


OUTPUT 


BLOCKOUTPUT 


OUTWORD 

X^ X^ A * • V / I X 1_S 


BLOCKOUTWORD 


RESTOREREALSTATUS 


BUILDPTR 


ROL 


CARRY 


ROR 


CAUSEINTERRUPT 


SAL 


CMPB 


SAR 


CMPW 


SAVEREALSTATUS 


DEC 


SCL 


DOUBLE 


SCR 


FINDB 


SELECTOROF 

^- j y — * j — - j — - v. jlx-/i.xx-/i 


FINDRB 


SETB 


FINDRW 


SFTRFAI MODF 


FINDW 


SETW 


FIX 


SHI 


FLAGS 


SHR 


FLOAT 


SIGN 


GETREALERROR 


SIGNFD 

1 VJ 1 > J_ii_/ 


HIGH 


SIZE 


IABS 


SKIPB 


INITRFAI MATHIJNIT 

J.I'll 1 1\ l-< iV l-< 1*1 A 1 llUlil 1 


SKTPRB 

Olxl I IxU 


INPUT 


SKIPRW 

kJ IV A J IX T t 


TNT 


oiYlr W 


INWORD 


STACKBASE 


LAST 


STACKPTR 


LOCKSET 


TIME 


LENGTH 


SIZE 


LOW 


UNSIGN 


MOVB 


XLAT 


MOVE 


ZERO 


MOVRB 
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PL/M Reserved Words and Predeclared Identifiers 



Additional reserved identifiers include: 



PL/M-86 



INTERRUPT 
SETINTERRUPT 

PL/M-286 and PL/M-386 

CLEARTASKSWITCHEDFLAG 

GETACCESSRIGHTS 

GETSEGMENTLIMIT 

LOCALTABLE 

MACHINESTATUS 

OFFSETOF 

PARITY 

RESTOREGLOBALTABLE 

PL/M-386 

CONTROLREGISTER 

DEBUGREGISTER 

FINDHW 

FINDRHW 

INHWORD 

MOVBIT 

MOVRBIT 

MOVHW 

MOVRHW 

PL/M-386 with WORD 16 control 

BLOCKINDWORD 

BLOCKOUTDWORD 

CMPD 

FINDD 

FINDRD 

INDWORD 



RESTOREINTERRUPTABLE 

SAVEGLOBALTABLE 

SAVEINTERRUPTTABLE 

SEGMENTREADABLE 

SEGMENTWRITABLE 

TASKREGISTER 

WAITFORINTERRUPT 



OUTHWORD 

SCANBIT 

SCANRBIT 

SETHW 

SHLD 

SHRD 

SKIPHW 

SKIPRHW 

TESTREGISTER 



MOVD 

MOVRD 

OUTDWORD 

SETD 

SKIPD 

SKIPRD 
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PL/M PROGRAM LIMITS 



The user-program features that have limits are listed below with their maximum 
values: 







Maximum 




Feature 


PL/M-86 


PL/M-286 


PL/M-386 


Size of LITERALLY string 


unlimited* 


unlimited* 


unlimited* 


Nesting of LITERALLY invocations 


5 


5 


5 


Nesting of INCLUDE controls 


5 


5 


5 


Number of nested procedures and DO cases 


255 


255 


255 


Number of labels on a statement 


unlimited* 


unlimited* 


unlimited* 


Nesting of blocks 


18 


18 


18 


Nesting of structures 


32 


32 


32 


Number of nested typed procedures 


20 


20 


18 


Number of elements in a factored list 


64 


64 


64 


Total number of members in a structure 








(at all levels) 


128 


128 


128 


Structure size 


64K-1 


64K-1 


4G-1 


Numbers of characters in a line 


128 


128 


128 


Length of a string constant 


255 


255 


255 


Number of DO blocks in a procedure 


65536 


65536 


65536 


Number of cases in a DO CASE block 


255 


255 


255 


Number of active cases 


255 


255 


255 


Number of declared EXTERNAL items 


unlimited* 


unlimited* 


** 


Number of EXTERNAL items used 


255 


255 


** 


Number of procedures in a module 


1015 


1015 


1015 


Segment size 


64K-1 


64K-1 


4G 


Symbol capacity 


See Note 


See Note 


2500 



* Limited by the total size of the symbol table 

* Limited by either the number of procedures or the number of symbols, or both. 
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PL/M-86/286 — 

I NOTE 
The PL/M-86 and PL/M-286 compilers have a symbol capacity of approxi- 
mately 5000 symbols. Of these, 800 are held in memory when the compiler has 
a partition size of 96K bytes. Any symbols over this amount will spill onto the 
workfiles disk, causing performance degradation. (If this happens, the com- 
piler will display a message to the console.) 

To increase performance, look at the dictionary summary (found in the compi- 
lation summary) to determine the amount of additional memory needed to avoid 
spilling to the disk. If another 64K bytes of memory is added to the compiler's 
partition (either by adding more memory to the system or by increasing its 
share of available memory), a total of 2300 symbols will then be held in 
memory. 



I 



end 

PL/M-86/286 



For large programs or programs with many symbols, providing the compiler 
with more memory to work in will improve its performance. 
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PL/M Program Limits 




GRAMMAR OF THE 
PL/M LANGUAGE 



inteT" 



This appendix lists the entire syntax of the PL/M language in Backus Naur Form 
(BNF). Since the semantic rules are not included here, this syntax permits certain 
constructions that are not actually allowed. The terminology used in the BNF syntax 
has been designed for convenience in constructing concise and rigorous definitions. 
Its appearance differs substantially from the main body of the manual. 

The notations used here are slightly extended from standard BNF notations. An ellip- 
sis (...) indicates that the syntactic element preceding it can be repeated indefinitely. 
The vertical bar ( | ) separates alternatives. Braces ( { } ) indicate that only one of the 
items within them can be used. Brackets ( [ ] ) indicate options. When items are 
stacked vertically within brackets, only one of the items can be used. 
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C.1 Lexical Elements 
£1.1 Character Sets 



< character >:: = < apostrophe > | < non-quote character > 
<apostrophe>:: = ' 

< non-quote character > :: = < letter > 

| < decimal digit > 

l$ 

| < special character > 
| blank 

< letter >:: = < uppercase letter> | < lowercase letter > 

< uppercase letter >::= A |B|C|D| E|F|G|H| I | 

J | K | L j M | N f O j P | Q | R | 
S | T | U | V | W | X I Y ( Z 

< lowercase letter> ::=a|b|c|d|e|f|g|h|i| 

j|k| I | m | n | o | p | q | r | 
s | t | u | v | w | x | y | z 

<decimaldigit>::=0 |1|2|3|4|5|6|7|8|9 

< special character >::= + |- |*|/|<|>| = | :|;| 

■I ,| (l)l@l- 

C.1.2 Tokens 

< token > :: = < delimiter > 

| < identifier > 

| < reserved word > 

| < numeric constant > 

| < string > 

C.1 .3 Delimiters 

<delimiter>:: = <simple delimiter> | < compound delimiter> 
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< simple delimiter >:: = + |- |*|/|<|>| = 

• I . I (1)1® 

< compound delimiter >:: = <> | <= | >= |: = 



C.1.4 Identifiers 



< identifier >:: = < letter > 



< letter > 
< decimal digit > 
$ 



< reserved word > (For a list of reserved words, see Appendix A.) 



C.1.5 Numeric Constants 



< numeric constants-:: = < binary number> 
| < octal number> 
| <decimal number> 
| < hexadecimal number> 
| < floating point number> 



< binary number>::=< binary digit> |j <binary digit> 
< octal number>:: = < octal digit> ^ < octal digit > 



.B 
Q 

O 
Q 



<decimal number>:: = <decimal digit > 



< hexadecimal number > :: = < decimal digit > 



< decimal digit > 



< hexadecimal digit > 
$ 



< floating point number >::=< digit string > < fractional part > 

[< exponent part>] 

< fractional part >:: = [< .digit string > ] 
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< exponent part >:: = E [+ | — ] < digit string > 



< digit string> :: = <decimal digit > 



< decimal digit 
$ 



< binary digit > :: =0 | 1 

<octal digit > : : = < binary digit> |2|3|4|5|6|7 
< decimal digit > : : = <octal digit > | 8 | 9 

< hexadecimal digit >::=< decimal digit > |A|B|C|D|E|F 



C.1.6 Strings 



< string > :: = ' < string body element >. . . ' 

< string body element >:: = < non-quote character > 



C.1.7 PL/M Text Structure: Tokens, Blanks, and Comments 



< token > 
< separator > 

<separator>:: = blank | " | <comment> 
<comment>::= /*[< character >]. . .*/ 

C.2 Modules and the Main Program 

<compilation>:: = < module > [EOF] 

<module>:: = <module name>:<simple do block> 

< module name > :: = < identifier > 



<pl/m text>:: = 



C.3 Declarations 



< declaration >:: = < declare statement > | < procedure definition > 
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C.3.1 DECLARE Statement 



< declare statement >:: = DECLARE < declare element list > ; 

<declare element list > :: = <declare element >[,< declare element>]. . . 

< declare element >:: = < factored element > | <unfactorecl element > 

<unfactored element >:: = < variable element > 
| < literal element > 
| < label element > 

< factored element > :: = < factored variable element > 
| < factored label element > 

C.3.2 Variable Elements 

< variable element > :: = < variable name specifier > 

[< array specifier >] 

< variable type> 

[ < variable attributes > ] 

< variable name specifier > : : = < non-based name > 

| < based name > BASED < base specifier > 

< non-based name > :: = < variable name > 

< based name>::=<variablename> 
< variable name> :: = <identifier> 

< base specifier > : : = < identifier > [. < identifier > ] 

< variable attributes >:: = [PUBLIC] [< locator > < initialization >] 

| [EXTERNAL] [< constant attribute >] 

< locator > : : = AT( < expression > ) 
< constant attribute > :: = DATA 

< array specifier >:: = < explicit dimension > | < implicit dimension > 

< explicit dimension >:: =( < numeric constant> ) 

< implicit dimension >::=(*) 

< variable type >::=< basic type> | < structure type > 
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PL/M-86/286 



end 

PL/M 
PL/M 



< basic type >:: = INTEGER 
REAL 
POINTER 
SELECTOR 
BYTE 
WORD 
DWORD 
ADDRESS 



86/286 1 
386 — 



end 

PL/M 



< basic type > : : = Add ress 
BYTE 
HWORD 
DWORD 
QWORD 
CHARINT 
OFFSET 
SHORTINT 
INTEGER 
REAL 

SELECTOR 
POINTER 
OFFSET 



386 



C.3.3 Label Element 



< label element> :: = <identifier> LABEL 



PUBLIC 
EXTERNAL 



C.3.4 Literal Elements 



< literal element>::= < identifier > LITERALLY <string> 
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C.3.5 Factored Variable Element 



< factored variable element > : : = ( < variable name specifier > 

[,< variable name specifier >]. . .) 

[ < explicit dimension > ] < variable type > 

[< variable attributes >] 

C.3.6 Factored Label Element 

< factored label element>::=(< identifier 

PUBLIC 

[,<identifier>]. . .) LABEL EXTERNAL 



C.3.7 The Structure Type 

< structure type> :: = STRUCTURE (< member element > 
[,<member element>]. . .) 

< member element > :: = <unfactored member > 

| < factored member > 

< unfactored member> :: = member name [explicit dimension] 

variable type 

< member name >:: = <identifier> 

<factored member>:: = (member name(,member name)...) 

[explicit dimension] variable type 



C.3.8 Procedure Definition 



< procedure definition > :: = < procedure statement> 

[< declaration > . . .] [<unit>. . .] < ending > 

<procedure statements: = <procedure name> :PROCEDURE 

[ < formal parameter list > ] [ < procedure type > ] 
[< procedure attributes >]; 

<procedure name>:: = < identifier > 
< procedure type >:: = < basic type > 

< formal parameter list >:: =(<formal parameter >[,< formal parameter >]. . . ) 
<formal parameters: = < identifier 
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< procedure attributes > :: = 



< interrupt > 
EXTERNAL 

< interrupt > 
PUBLIC 

REENTRANT 



C.3.9 Attributes 

C.3.9.1 AT 

< locator > :: = AT ( < expression > ) 

C.3.9.2 INTERRUPT 

PL/M-86: 

< interrupt >:; = INTERRUPT < numeric constant > 

PL/M-286 and PL/M-386: 

< interrupt > :: = INTERRUPT 

C.3.9.3 Initialization 



< initialization >::= INITIAL (< initial value > [,< initial value >]. . .) | DATA 

< initial value >::=< expression > | < string > 



C.4 Units 



<unit>:: = < conditional clause > 
| <do block > 
| < basic statement > 
| < label definition >< unit > 

< basic statement > : : = < assignment statement > 
| < call statement > 
| < goto statement > 
| < null statement > 
[ < return statement > 
| < microprocessor dependent statement > 
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< scoping statement > :: = < simple do statement > 
| < do-case statement > 
| < do-while statement > 
| < iterative do statement > 
| <end statement > 
| < procedure statement > 

< label definition >:: = < identifiers 



C.4.1 Basic Statements 

C.4.1.1 Assignment Statement 



< assignment statement >:: = < left part > = < expression > ; 

< left part> :: = <variable reference> [,<variable reference>] 



C.4.1.2 CALL Statement 



<call statement>:: = CALL < simple variable>[< parameter lists]; 
< parameter list >:: = (< expression >[,< expression >] . . .) 
<simple variable>::= < identifiers | < identifier > . < identifiers 



C.4.1. 3 GOTO Statement 



< goto statements ::= < GOTO I <iden,ifier> ; 



C.4.1. 4 Null Statement 

< null statements :: = ; 
C.4.1.5 RETURN Statement 



< return statements ::= <typed returns | < untyped returns 

< typed return s : : = RETURN < expression s 
<untyped returns::= RETURN; 
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C.4.1.6 Microprocessor-Dependent Statements 

< microprocessor dependent statement > :: = < disable statement > 

| < enable statement > 

| < halt statement > 

| < cause interrupt statement > 

< disable statement >:: = DISABLE; 

< enable statement >:: = ENABLE; 

< halt statement >:: = HALT; 

< cause interrupt statements: = CAUSE$INTERRUPT (numeric constant); 

C.4.2 Scoping Statements 

C.4.2.1 Simple DO Statement 

< simple do statement >:: = DO; 
C.4.2.2 DO-CASE Statement 

< do-case statement >:: = DO CASE <expression> ; 
C.4.2.3 DO- WHILE Statement 

< do-while statement >:: = DO WHILE < expression > ; 
C.4.2.4 Iterative DO Statement 

< iterative do statement >::= DO < index part >< to part > [<bypart>]; 

< index part >::= < index variable> = < start expression > 
<topart>::= TO < bound expression > 
<bypart>::= BY < step expression > 

< index variable > :: = < simple variable > 
< start expression > :: = < expression > 

< bound expression >:: = < expression > 
<step expression >:: = < expression > 

C.4.2.5 END Statement 

<end statements: = END [< identifier>]; 



C-10 



Grammar of the PL/M Language 



C.4.2.6 Procedure Statement 



< procedure statement> :: = < procedure name> : PROCEDURE 
[< formal parameter list > ] [< procedure type>] 
[< procedure attributes >]; 

C.4.3 Conditional Clause 

< conditional clause>::= <if condition > <true unit> 

| < if condition > < true element > ELSE < false element > 

< if condition >:: = IF < expression > THEN 

<true element>:: = [<label definition > . . .] <do block> 

| [< label definition > . . .] < basic statement > 

<false element>:: = <unit> 
<true unit>::= <unit> 

C.4.4 DO Blocks 

<do block> :: = <simple do block> 
| < do-case block > 
| < do-while block > 
| < iterative do block > 

C.4.4.1 Simple DO Blocks 

< simple do block>:: = < simple do statement >[< declarations . .] 
[<unit>. . .]<ending> 

< ending>:: = [< label definition > . . .]<end statement> 
C.4.4.2 DO-CASE Blocks 

< do-case block >::=< do-case statement > [<unit>. . .] < ending > 
C.4.4.3 DO-WHILE Blocks 

< do-while block>::= < do-while statement > [<unit>. . .] <ending> 
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C.4.4.4 Iterative DO Blocks 



< iterative do block >::=< iterative do statement > [<unit>. . .] <ending> 

C.5 Expressions 
C.5.1 Primaries 

< primary >::= <constant> 

| < variable reference > 
| < location reference > 
| < subexpression > 

< subexpression >:: = ( < expression > ) 
C.5. 1.1 Constants 

< constant >:: = < numeric constant > | < string > 
C.5. 1.2 Variable References 

< variable reference >::=< data reference > | < function reference > 

<data reference>::= <name>[<subscript>] [<member specifier>] 

< subscript >:: = (< expression >) 

< member specifier > : : = . < member name > [ < subscript > ] 
<function references: = <name>[< actual parameters>] 
<actual parameters>::=(<expression>[,<expression>]. . .) 

< member name>:: = <identifier> 
<name>::= < identifier > 

C.5. 1.3 Location References 

< location reference >:: = @ < constant list > 

| @ < variable reference > 

< constant list >:: = (< constant >[,< constant >]. . .) 
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C.5.2 Operators 



< operator >:: = < logical operator > 
| < relational operator > 
| < arithmetic operator > 

< logical operators: = AND | OR | NOT | XOR 

< relational operator >:: = <|>|<=|>=|<>| = 

< arithmetic operator >::= + | - | PLUS | MINUS | * | / | MOD 

C.5.3 Structure of Expressions 

< expression > : : = < logical expression > 

| < embedded assignment > 

< embedded assignment >:: = < variable reference > := < logical expression > 

< logical expression > : : = < logical factor > 

| < logical expression > < or operator >< logical factor > 

<oroperator>::=OR | XOR 

< logical factor> :: = < logical secondary> 

| < logical factor > < and operator >< logical secondary > 

<and operator>::= AND 

< logical secondary >:: = [< not operator >] < logical primary > 

< not operator >:: = NOT 

< logical primary>::= < arithmetic expression > 

[ < relational operator > < arithmetic expression > ] 

< relational operator >:: = < | > |<=|>=|<>| = 

< arithmetic expression > :: = < term > 

< arithmetic expression > < adding operator > < term > 

< adding operator;.:: = + | - | PLUS | MINUS 

< term > : : = < secondary > 

| <term> < multiplying operator> <secondary> 

< multiplying operator> :: = * | / | MOD 

< secondary >:: = <unaryminus> <primary> <unaryplus> 

< unary minus>:: = - 

< unary plus> :: = + 
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DIFFERENCES AMONG 
PL/M-86, PL/M-286, AND PL/M-386 



D.1 Differences between PL/M-86 and PL/M-80 

PL/M-86 differs from PL/M-80 in the following respects: 

• Support for floating-point arithmetic 

• Support for signed arithmetic 

• Addition of REAL, INTEGER, POINTER and SELECTOR data types 

• Addition of the @ location reference operator 

• Support for nested structures 

• Expanded set of built-in procedures 

In addition, the PL/M-80 reserved word ADDRESS is replaced by the PL/M-86 
reserved word WORD. PL/M-80 has only the BYTE and ADDRESS data types. 
However, PL/M-86 has the following data types: BYTE, WORD, DWORD, 
INTEGER, REAL, POINTER, and SELECTOR. 

The PL/M-86 rules for expression evaluation are more complete than those of 
PL/M-80. Other differences stem from the ones noted here. For example, an iterative 
DO block operates differently if its index variable is an INTEGER variable. 

D.2 Compatibility of PL/M-80 Programs and the 
PL/M-86 Compiler 

PL/M-80 programs that operate correctly on an 8080 microprocessor can be recom- 
piled with the PL/M-86 compiler to produce code that will run on an 8086 micropro- 
cessor. First edit the PL/M-80 source code as follows: 

• PL/M-80 source code identifiers that are PL/M-86 reserved words must be 
changed. 

• It is not necessary to change ADDRESS to WORD; ADDRESS is a PL/M-86 
reserved word with the same meaning as WORD. 
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Note that where PL/M-86 programs would normally have POINTER variables and 
location references formed with the @ operator, PL/M-80 programs have ADDRESS 
(WORD) variables and location references formed with the dot operator. PL/M-80 
usage is less restricted than PL/M-86 usage, because arithmetic operations can be 
used on WORD values. In general, the PL/M-86 compiler supports PL/M-80 usage 
to provide upward compatibility. Some restrictions affect the types of expressions 
that can be used in the AT attribute, the INITIAL and DATA initializations, and 
location references. See also the discussions of size controls and the dot and @ 
operators in this manual. 



D.3 Differences between PL/M-286 and PL/M-86 

PL/M-286 differs from PL/M-86 in the following respects: 

• POINTER and SELECTOR variables cannot be assigned absolute (i.e., con- 
stant) values. Only the equals operator ( = ) can be used with POINTER vari- 
ables. For SELECTOR variables the logical (AND, OR, NOT, XOR) and rela- 
tional (<, >, <=, >=, <>, =) operators can be used. 

• Access to the hardware flag register is provided with the built-in variable 
FLAGS. 

• Four built-in functions have been added to support multiple byte and word input: 
BLOCKINPUT, BLOCKINWORD, BLOCKOUTPUT, and BLOCKOUTWORD 
(available to PL/M-86 via the MOD86/MOD186 control). 

• The type of the STACKBASE variable has been changed from WORD to 
SELECTOR. 

• New built-in procedures and functions have been added to support the 80286 
hardware protection model. 

• Interrupt procedures are no longer assigned numbers in the source program. 
(This is done by the 80286 system builder.) Interrupt procedures also cannot be 
called directly, and the SETSINTERRUPT and INTERRUPTSPTR built-ins have 
been removed. 

• The memory array has been removed. 
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D.4 Compatibility of PL/M-86 Programs and the 
PL/M-286 Compiler 

PL/M-86 programs that operate correctly on an 8086 microprocessor can be recom- 
piled with the PL/M-286 compiler to produce code that will run on an 80286 micro- 
processor. The PL/M-86 source code must be edited as follows: 

• Assignments to the STACKBASE built-in variable must be changed from WORD 
to SELECTOR. 

• All absolute pointer and selector assignments must be changed. (Pointers can be 
assigned a zero value using the new built-in function NIL.) Also, relational oper- 
ations on pointer and selector values for any operation other than equality and 
inequality must be changed. 

• The interrupt numbers on all interrupt procedures must be deleted. Interrupt 
vectors will be assigned to these procedures by the 80286 system builder. Direct 
calls to interrupt procedures must also be changed. 

• References to the SET$INTERRUPT, INTERRUPT$PTR, and MEMORY built- 
ins must be removed. 

D.5 Differences between PL/M-386 and PL/M-286 

PL/M-386 differs from PL/M-286 in the following respects: 

• The string built-ins FIND, CMP, and SKIP return a value of OFFFFFFFFH for 
the not found and string equal results. 

• Support for 64-bit unsigned scalars. 

• Support for 8-bit and 32-bit signed scalars. 

• Addition of HWORD, CHARINT, and SHORTINT data types. 

• ADDRESS is the same as OFFSET (and not as WORD as in PL/M-286) . 

• Support for WORD32 and WORD 16 mapping for data type identifiers. 

• Addition of the WORD32/WORD16 primary compiler controls, which ensure 
PL/M data type and language compatibility. 

• MEDIUM and LARGE segmentation controls no longer indicate unique mean- 
ing to the compiler; MEDIUM is interpreted as SMALL and LARGE is inter- 
preted as COMPACT except when LARGE is used to indicate a subsystem whose 
name is unknown at compile time. 
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• Several new built-in procedures and functions have been added to support the 
new data types (for example, CMPHW, BLOCKINHWORD; see Chapters 9 and 
10), and some bit-string operations (for example, SCANBIT, MOVBIT). 

• The built-ins CONTROL$REGISTER, DEBUG$REGISTER, and TEST 
$REGISTER have been added to support the 80386 microprocessor. 

D.6 Compatibility of PL/M-286 Programs and the 
PL/M-386 Compiler 

PL/M-286 source code can be compiled with the PL/M-286 compiler to produce 
code that will run on an 80386 microprocessor in 80286 microprocessor mode and 
interface with PL/M-386 code through INTERFACE(/286). In addition, PL/M-286 
programs that operate on an 80286 microprocessor can be recompiled with the 
PL/M-386 compiler to produce code that will run on an 80386 microprocessor in the 
native 80386 microprocessor mode. 
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ASCII CHARACTERS, HEX VALUES, 
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LINKING TO MODULES 
WRITTEN IN OTHER LANGUAGES 

F.1 Introduction 

This appendix describes the calling conventions used by the 80[jr]86 family of lan- 
guages. These calling conventions are standardized so that a module written in PL/M 
can freely call procedures, subroutines, and subprograms in other modules written in 
other 80[.v]86 languages. 

The information in this appendix is not necessary to call PL/M procedures and func- 
tions from PL/M. See Chapter 8 for information about parameters and arguments. 

The calling conventions and stack and register usage described in this appendix are 
needed to call ASM subroutines. Also, the corresponding data types listed at the end 
of this appendix are needed to write a subroutine that can pick up the data in the PL/ 
M program. Refer to the ASM macro assembler operating instructions for more 
information about combining PL/M programs with ASM programs and for exam- 
ples. 

The easiest way to ensure compatibility between assembly-language subroutines that 
are combined with PL/M programs or procedures is to write a dummy procedure in 
PL/M. This procedure would have the same argument list and the same attributes as 
the desired assembly language subroutine. The PL/M procedure would then be com- 
piled with the correct segmentation control, and the CODE control specified. This 
will produce a pseudo-assembly listing of the generated microprocessor code, which 
can then be copied to the prologue and epilogue of the assembly language subroutine. 

With PL/M, separate modules can be written and compiled, and combined at a later 
time. This allows you to create separately tested modules that are combined after they 
are internally bug-free. Not all modules have to be in PL/M: you can choose the 
appropriate language for each module. Be sure to combine the modules properly with 
a binder or a linker in order to satisfy references to externals. Because the 80[*]86 
languages (excluding C) follow the same calling sequence, control will pass to a 
called module correctly. (The C calling sequence is described in Section F.7. The 
standard calling sequence is described in the following section.) However, the called 
module might not be able to deal intelligently with the data passed to it since lan- 
guages treat some data structures differently. 
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By specifying arguments in a reference to an external procedure, data is passed to the 
external procedure. The number of arguments and the order in which they are speci- 
fied must match the number and order of the corresponding parameters in the exter- 
nal procedures declaration (see Chapter 8). 

All arguments for parameters are passed on the microprocessor's stack, or the nu- 
meric coprocessor's register stack, in the order in which they were specified. For the 
80386 microprocessor, the space occupied by a parameter pushed on the micropro- 
cessor's stack is always a multiple of four bytes. For the 8086 and 80286 micropro- 
cessors, the space occupied by a parameter pushed on the microprocessor's stack is 
always a multiple of two bytes. Functions return non-real values in a register, and 
REAL values on the top of the numeric coprocessor's register stack. 

F.2 Calling Sequence 

The calling sequence for each procedure activation places the procedure's actual pa- 
rameters (if any) on the stack and then activates the procedure with a CALL 
instruction. 

Parameters are placed on the microprocessor's stack or the numeric coprocessor's 
register stack in left-to-right order. Because the stack grows from higher locations to 
lower locations, the first parameter occupies the highest position on the stack, and the 
last parameter occupies the lowest position. Stack representation for the different 
PL/M parameters is described in Table F-l . 



Table F-l Stack Representation for PL/M Parameters 



Parameter 


8086 and 80286 
Stack Representation 


80386 
Stack Representation 


BYTE 


Two bytes, with the higher 
byte undefined. 


Four bytes, with the higher 
three bytes undefined. 


CHARINT 


N/A 


Four bytes, with the higher 
three bytes undefined. 


HWORD 


N/A 


Four bytes, with the high two 
bytes undefined. 


SELECTOR 


N/A 


Four bytes, with the high two 
bytes undefined. 
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Table F-l Stack Representation for PL/M Parameters (continued) 



Parameter 


8086 and 80286 
Stack Rporesentation 


80386 
Stack Representation 


SHORTINT 


N/A 


Four bytes, with the high two 
bytes undefined. 


WORD 


Two bytes, with no undefined 
bytes. 


Four bytes, with no unde- 
fined bytes. 


OFFSET 


N/A 


Four bytes, with no unde- 
fined bytes. 


INTEGER 


N/A 


Four bytes, with no unde- 
fined bytes. 


REAL 


N/A 


Four bytes, with no unde- 
fined bytes. 


DWORD 


Four bytes, with the high 16 
bits pushed first and the low 
16 bits pushed second. 


Eight bytes with the high 32 
bits pushed first and the low 
32 bits pushed second. 



For the 8086 and the 80286 microprocessors, a POINTER parameter in the 
SMALL(ROM), COMPACT, MEDIUM, and LARGE cases consists of a selector 
and an offset. The 16-bit selector is pushed first, followed by the 16-bit offset. 

For the 80386 microprocessor, a POINTER parameter in the SMALL(ROM) and 
COMPACT cases consists of a selector and an offset. The 16-bit selector is pushed 
first, followed by the 32-bit offset. 

The left-most seven REAL parameters are passed on the numeric coprocessor's 
stack. If more than seven REAL parameters are present, the rest (after the left-most 
seven) are passed on the microprocessor's stack and are intermixed with the other 
non-real parameters in the order in which all parameters were declared. 

After the parameters are passed, the CALL instruction places the return address on 
the stack. In the SMALL and COMPACT cases with local (or non-exported) proce- 
dures, for the 8086 and the 80286 microprocessors, this address is a 16-bit offset (the 
contents of the IP register) and occupies two contiguous bytes on the stack. For the 
80386 microprocessor, this address is a 32-bit offset (the contents of the EIP register) 
and occupies four bytes on the stack. 

Specific to the 8086 and the 80286 microprocessors, in the MEDIUM and LARGE 
cases, and for procedures exported from COMPACT, the type of the return address 
depends on whether the procedure is local or public. The return address for a local 
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procedure, like any return address for the SMALL case, is a 16-bit offset and occu- 
pies two contiguous bytes on the stack. For a public procedure in the MEDIUM or 
LARGE case, and for procedures exported from a subsystem, the return address is a 
POINTER value consisting of a selector and an offset; the return address is passed in 
the same way a POINTER parameter is passed. The 16-bit segment selector (contents 
of the CS register) is pushed first, then the 16-bit offset (IP register contents) is 
pushed. 

Specific to the 80386 microprocessor, for procedures exported from a subsystem, the 
return address is a POINTER value consisting of a selector and offset; the return 
address is placed on the stack in the same way a POINTER parameter is passed. The 
16-bit segment selector (contents of the CS register) is pushed first, then the 32-bit 
offset (EIP register contents) is pushed. 

For all of the microprocessors, control is passed to the code of the procedure by 
updating the IP register for the 8086 and the 80286 microprocessors and the EIP 
register for the 80386 microprocessor. For procedures exported from a subsystem, 
the CS register is also updated. 

Figure F-l shows the stack layout at the point where the procedure gains control. 
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Figure F-l Stack Layout at Point Where a Non-interrupt Procedure is Activated 
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F.3 Procedure Prologue 



In compiling the procedure itself, the compiler inserts a sequence of instructions 
called the procedure prologue. The procedure prologue varies depending on the type 
of procedure being compiled as follows: 

• If the procedure has the PUBLIC attribute and the program size is LARGE, or if 
it is exported from a subsystem, the content of the DS register is placed on the 
stack and is then updated to the data segment of the procedure. Additionally, for 
the 80386 microprocessor, ES is set to DS. (For the 8086 and the 80286 micro- 
processors, the DS register contains the segment selector for the current data 
segment; thus, this step implements the pairing of code and data segments in the 
LARGE case. It is not needed in the SMALL, COMPACT, and MEDIUM cases 
because the data segment does not change.) 

• If any parameter of the procedure is referenced by a nested procedure, all param- 
eters are copied from the stack to space reserved for them in the data segment. 

• The stack marker offset (the 8086 and the 80286 microprocessors' BP register 
contents, and the 80386 microprocessor's EBP register contents) is placed on the 
stack, and the current stack pointer (the 8086 and the 80286 microprocessors' SP 
register contents, and the 80386 microprocessor's ESP register contents) is used 
to update the BP or EBP register. 

• If the procedure has the REENTRANT attribute, space is reserved on the stack 
for any variables declared within the procedure (this does not include based 
variables, variables with the DATA attribute, or variables with the AT attribute). 

Control then passes to the code compiled from the executable statements in the proce- 
dure body. Figure F-2 shows the stack layout at this point. 
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Figure F-2 Stack Layout During Execution of a Non-interrupt Procedure Body 



F.4 Procedure Epilogue 

To return from the procedure, the compiler inserts an instruction sequence called the 
epilogue. This accomplishes the following: 

• If the compiler has used stack locations for temporary storage or local variables 
during procedure execution, the stack pointer (the SP register for the 8086 and 
the 80286 microprocessors, and the ESP register for the 80386 microprocessor) 
is loaded with the stack marker (the BP register for the 8086 and the 80286 
microprocessors, and the EBP register for the 80386 microprocessor), discard- 
ing the temporary storage. 

• The old stack marker is restored by popping the stored value from the stack into 
the BP or the EBP register. 
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• If the procedure has the PUBLIC attribute and the program size is LARGE or it 
is exported from a subsystem, the old data segment selector is restored by pop- 
ping the stored value from the stack into the DS register. Additionally, for the 
80386 microprocessor, ES is set to DS. 

• For the 8086 and the 80286 microprocessor, if the program size is SMALL, the 
stored return address (a 16-bit offset) is popped into the IP register. Any parame- 
ters stored on the stack are discarded. 

• For the 80386 microprocessor, the stored return address (a 32-bit offset) is 
popped into the EIP register. If the procedure is exported, the stored return 
address selector is also popped into the CS register. Any parameters stored on the 
stack are discarded. 

Specific to the 8086 and the 80286 microprocessors, if the program size is MEDIUM 
or LARGE and the procedure is local, a return is performed using the actions previ- 
ously described. If the program size is MEDIUM or LARGE and the procedure is 
public, the stored return-address offset from the stack is popped into the IP register 
and the return-address selector is popped into the CS register. Any parameters not 
stored on the stack are discarded. 

F.5 Register Usage 

Table F-2 provides a summary of the 8086 and the 80286 microprocessor register 
usage. Table F-3 provides a summary of the 80386 microprocessor register usage. 



Table F-2 Summary of the 8086 and the 80286 Microprocessor Register Usage 



Register 


Must Preserve 


Usage 


AX 


No 


Return BYTE (AL), WORD, DWORD, 
INTEGER, and SELECTOR values; 
POINTER offset when using C lan- 
guage interface. 


BX 


No 


Return POINTER offset values. 


CX 


No 




DX 


No 


Return DWORD values; POINTER 
segment selector when using C lan- 
guage interface. 


SP 


Yes* 


Stack pointer 


BP 


Yes 


Stack marker 
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Table F-2 Summary of the 8086 and the 80286 Microprocessor 
Register Usage (continued) 



Register 


Must Preserve 


Usage 


SI 


No (Yes when using C 
language interface.) 


— 


Dl 


No (Yes when using C 
language interface.) 




FLAGS 


No 


— 


CS 


Yes 


Called procedure's code segment. 


DS 


Yes 


Caller's data segment. 


ss 


Yes 


Caller's stack segment. 


ES 


No (Yes when using C 
language interface.) 


Return POINTER segment selector. 


*SP must be adjusted so that all arguments are removed from the stack on return. 


Table F-3 Summary of the 80386 Microprocessor Register Usage 


Register 


Must Preserve 


Usage 


EAX 


No 


Return BYTE (AL), HWORD (AX), 
WORD, DWORD, CHARINT (AL), 
SHORTINT (AX), INTEGER, SELEC- 
TOR (AX), POINTER offset portion, 
and OFFSET. 


EBX 


No (Yes when using C 
language interface.) 




ECX 


No 




EDX 


No 


Return upper half of DWORD values, 
POINTER segment selector. 


ESP 


Yes* 


Stack pointer 


EBP 


Yes 


Stack marker 


ESI 


No (Yes when using C 
language interface.) 




EDI 


No (Yes when using C 
language interface.) 




FLAGS 


No 
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Table F-3 Summary of the 80386 Microprocessor Register Usage (continued) 



negister 


must Kreserve 


usage 


WO 


I CO 




DS 


Yes 


Caller's data segment. 


SS 


Yes 


Caller's stack segment. 


ES 


Yes 


Caller's data segment. 


FS, GS 


No 





*ESP must be adjusted so that all arguments are removed from the stack on return (except 
when using C language interface). 



The numeric coprocessor's stack contains the first seven REAL arguments passed by 
the calling program. The numeric coprocessor's status word is unknown and does not 
need to be saved. If the status word is changed, the numeric coprocessor's mode word 
must be saved on entry and restored before exit. 

If an assembly language subroutine alters the DS or SS registers, and expects to be 
called by a PL/M program, the subroutine must save the contents of these registers 
upon entry and restore them before returning to the PL/M program. Additionally, for 
the 80386 microprocessor, the CS and ES registers must be preserved by the called 
procedure. 

PL/M uses the 8086 and the 80286 microprocessors' BP register or the 80386 micro- 
processor's ESP and EBP registers to address the stack. If a called assembly language 
subroutine uses the stack register, the subroutine must save the contents of the register 
on entry and restore the register's contents before returning control to the PL/M 
program. Before returning, the called subroutine must also adjust the 8086 and the 
80286 microprocessors' SP register or the 80386 microprocessor's ESP register to 
remove all parameters from the microprocessor's stack. Additionally, specific to the 
80386 microprocessor, the CS and ES registers must be preserved by the called 
procedure. 

For the 8086 and the 80286 microprocessors, the AX, BX, CX, DX, SI, DI, and ES 
registers do not need to be preserved. For the 80386 microprocessor, the EAX, EBX, 
ECX, EDX, ESI, EDI, FS, and GS registers do not need to be preserved. A called 
subroutine can freely use these registers. 

An assembly language program calling a PL/M procedure cannot expect the con- 
tents of the general-purpose registers (except BP and SP for the 8086 and the 80286 
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microprocessors, and EBP and ESP for the 80386 microprocessor) to be preserved. 
If the contents of these registers are needed, they must be saved prior to calling the 
PL/M procedure. 

Table F-4 summarizes the 8086, 80286, and 80386 microprocessor registers used to 
hold simple data types that are returned by typed procedures. 

NOTE 

Returning a pointer to a gate, an unreadable code segment, or a segment that is 
not accessible at the caller's privilege level will cause a protection fault for the 
80286 microprocessor. Also, an attempt to return a pointer to a segment that is 
not accessible at the called procedure's privilege level but is accessible at the 
caller's level will result in the caller receiving a null selector. 



Table F-4 Registers Used to Hold Simple Data Types 



8086 and 80286 
Microprocessors 
Procedure Type 


80386 
Microprocessor 
Procedure Type 


Register 


BYTE 


BYTE 
CHARINT 


AL 


WORD 


HWORD 
SHORTINT 


AX 


DWORD 




DX:AX 


INTEGER 




AX 




WORD 

OFFSET 

INTEGER 


EAX 




DWORD 


EDX:EAX 


POINTER(SMALL)* 




BX (AX when using the 
C language interface.) 


POINTER(COMPACT) 




ES:BX (DS:AXwhen 
using the C language 
interface.) 


POINTER(MEDIUM) 




ES:BX (DS:AX when 
using the C language 
interface.) 
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Table F-4 Registers Used to Hold Simple Data Types (continued) 



8086 and 80286 
Microprocessors 
Procedure Type 


80386 
Microprocessor 
Procedure Type 


Register 






to. da (Uo.ma wnen 
using the C language 
interface.) 




rUIIM 1 tn (oMUM 1, 

SMALL RAM) 


PAY 
tnA 




POINTER (LONG, 
COMPACT, SMALL 
ROM) 


EDX:EAX 


SELECTOR 


SELECTOR 


AX 


REAL 


REAL 


Top of the numeric 
coprocessor's stack. 



*Underthe ROM option, the result is returned in ES:BX (DX:AX when using the C language 
interface). 



F.6 Segment Name Conventions 

Tables F-5 through F-7 summarize the segmentation of a subsystem under the pro- 
gram segmentation controls (SMALL and COMPACT for the 80386 microproces- 
sor). The name of the segment in which each type of program section is stored (for 
each control, and for subsystems) is shown. 



Table F-5 Summary of PL/M-86 Segment Names 



Model 


SubModel 


Code 


Data 


Const 


Stack 


SMALL 


IN DATA 


CODE 


DATA 


CONST 


STACK 


IN CODE 


CODE 


DATA 


CONST 


STACK 


SMALL 
(subsystem) 


IN DATA 


sCODE 


DATA 


DATA 


DATA 


IN CODE 


sCODE 


DATA 


sCODE 


DATA 


COMPACT 


IN DATA 


CODE 


DATA 


CONST 


STACK 


IN CODE 


CODE 


DATA 


CONST 


STACK 


COMPACT 
(subsystem) 


IN DATA 


sCODE 


sDATA 


CONST 


STACK 


IN CODE 


sCODE 


sDATA 


CONST 


STACK 
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Table F-5 Summary of PL/M-86 Segment Names (continued) 



Model 


SubModel 


Code 


Data 


Const 


Stack 


MEDIUM 


IN DATA 


mCODE 


DATA 


CONST 


STACK 


IN CODE 


mCODE 


DATA 


CONST 


STACK 


LARGE 


IN DATA 


mCODE 


mDATA 


mDATA 


STACK 


IN CODE 


mCODE 


mDATA 


mCODE 


STACK 


LARGE 
(subsystem) 


IN DATA 


mCODE 


mDATA 


mDATA 


STACK 


IN CODE 


mCODE 


mDATA 


mCODE 


STACK 



Notes: sCODE denotes a segment name composed of the subsystem name and CODE. 
sDATA denotes a segment name composed of the subsystem name and DATA. 
mCODE denotes a segment name composed of the module name and CODE. 
mDATA denotes a segment name composed of the module name and DATA. 



Table F-6 Summary of PL/M-286 Segment Names 



Model 


SubModel 


Code 


Data 


Const 


Stack 


SMALL 


IN DATA 


CODE 


DATA 


DATA 


STACK 


IN CODE 


CODE 


DATA 


CODE 


STACK 


SMALL 

(subsystem) 


IN DATA 


sCODE 


DATA 


DATA 


DATA 


IN CODE 


sCODE 


DATA 


sCODE 


DATA 


COMPACT 


IN DATA 


CODE 


DATA 


DATA 


STACK 


IN CODE 


CODE 


DATA 


CODE 


STACK 


COMPACT 
(subsystem) 


IN DATA 


sCODE 


sDATA 


sDATA 


STACK 


IN CODE 


sCODE 


sDATA 


sCODE 


STACK 


MEDIUM 


IN DATA 


mCODE 


DATA 


DATA 


DATA 


IN CODE 


mCODE 


DATA 


mCODE 


DATA 


LARGE 


IN DATA 


mCODE 


mDATA 


mDATA 


STACK 


IN CODE 


mCODE 


mDATA 


mCODE 


STACK 


LARGE 
(subsystem) 


IN DATA 


mCODE 


mDATA 


mDATA 


STACK 


IN CODE 


mCODE 


mDATA 


mCODE 


STACK 



Notes: sCODE denotes a segment name composed of the subsystem name and CODE. 
sDATA denotes a segment name composed of the subsystem name and DATA. 
mCODE denotes a segment name composed of the module name and CODE. 
mDATA denotes a segment name composed of the module name and DATA. 
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Table F-7 Summary of PL/M-386 Segment Names 



Model 


SubModel 


Code 


Data 


Const 


Stack 


SMALL 


IN DATA 


CODE32 


DATA 


DATA 


DATA 


IN CODE 


CODE32 


DATA 


CODE32 


DATA 


SMALL 
(subsystem) 


IN DATA 


S_CODE32 


DATA 


DATA 


DATA 


IN CODE 


S_CODE32 


DATA 


S_CODE32 


DATA 


COMPACT 


IN DATA 


S_CODE32 


S_DATA 


S_CODE32 


STACK 


IN CODE 


S_CODE32 


S_DATA 


S_CODE32 


STACK 


COMPACT 
(subsystem) 


IN DATA 


S_CODE32 


DATA 


S_DATA 


STACK 


IN CODE 


S_CODE32 


DATA 


S_CODE32 


STACK 



Notes: CODE32 denotes a segment name composed of CODE32. 
DATA denotes a segment name composed of DATA. 

S_CODE32 denotes a segment name composed of the subsystem name and CODE32. 
S_DATA denotes a segment name composed of the subsystem name and DATA. 



F.7 C Language Compatibility 

The C-86/286 calling conventions, procedure prologue and epilogue, and register 
usage differ from other Intel 80286 languages. However the INTERFACE control, 
described in Section 11.2.7, allows C procedures to call procedures written in PL/M 
and vice versa. 

— PL/M-386 

The calling conventions, procedure prologue and epilogue, and register usage for 
C-386 language differ from the other Intel 80386 microprocessor languages. These 
difference are as follows: 

• All parameters (real and non-real), are passed on the microprocessor's stack. 
The last parameter is pushed first and the first parameter is pushed last so that the 
first parameter is in the lowest memory location. 

• An integral parameter that is less than four bytes must be zero or sign-extended, 
as required by the C language. 

• The space occupied by a parameter pushed on the microprocessor stack is always 
a multiple of four bytes. 
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PL/M-386 — 

(continued) 

• Both short (floating-point) and long (double) real parameters are pushed as long 
real parameters, as required by the C language. Therefore, all real parameters 
passed from or to C procedures must be typed as 64-bit REAL in the PL/M-386 
code. 

• The calling procedure pops the parameters from the microprocessor stack after 
the called procedure has returned. Except when the called procedure is a func- 
tion returning real results, the called procedure must not leave any entries in the 
numeric coprocessor stack. 

• The ESP, EBP, CS, DS, ES, and SS registers should be preserved by the called 
procedure. (They are used for global storage.) 

• The EBX, ESI, and EDI registers should also be preserved by the called proce- 
dure. These registers can be used by the caller for local data storage. 

• The EAX, ECX, EDX, FS, and GS registers do not need to be preserved by the 
called procedure. 

See the description of the INTERFACE control, in Chapter 11, for information on 
how to call C procedures from procedures written in PL/M-386, and vice versa. 

end 

PL/M-386 

PL/M-86 — 

F.8 Floating-point Libraries 



This section deals with choosing the appropriate linkage specification to use the 
REAL math facility. The options are no use, PL/M-86 use only, or use of routines not 
written in PL/M-86. Choosing the correct linkage specification also depends on 
whether execution will use an actual numeric coprocessor or an 8087 emulator. 



These linkage specifications make available the libraries of floating-point functions. 
The circumstances determining which library is appropriate are given in Table F-8. 
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(continued) 



Table F-8 Linkage Choices for REAL-Math Usage 



1 1 <~ n n( DC A 1 

Use 01 HtAL 

Math Facility 


Emulator or 
Numeric Coprocessor 


1 inl/ lie** 

LinK-IISt 

Specifications 


None 

All floating point in PL/M-86 
only 

With some modules that use 
floating point not in PL/M-86. 

Any 


Neither 
Emulator 

Emulator 

Numeric coprocessor 


(none) 
E8087.LIB 

E8087.LIB, E8087 

8087.LIB 



The interface libraries do the following: 

• 8087. LIB resolves external references inserted by the translator of an 8086 mi- 
croprocessor program so that floating-point instructions will correctly invoke the 
numeric coprocessor. 8087. LIB is the library of floating-point functions written 
for the numeric coprocessor rather than for the 8087 emulator. 

• E8087.LIB resolves such references to invoke the 8087 emulator software in- 
stead of the actual numeric coprocessor. 

Emulation is performed by E8087. 

• E8087 is the emulation routines library, which provides all the functions and 
features of a numeric coprocessor, except speed. Emulation is invoked automati- 
cally using interrupts 20 through 31. The emulator occupies approximately 16K 
bytes of code space. 

The 8087 emulator processes exceptions exactly as the numeric coprocessor does. 
However, if the microprocessor/numeric coprocessor implementation includes an ex- 
ternal interrupt masking device such as an 8259A, the effect of this external device 
cannot be simulated by the 8087 emulator. An interrupt 16 occurs after execution of 
any instruction when the emulated interrupt is active and the microprocessor interrupt 
is enabled, even if the 8259 A is disabled. 
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PL/M-86 — 

(continued) 

I To locate the 8087 emulator at a specified memory location: 
• Locate the read-only code by referring to class AQMCODE in the LOC86 
invocation. 

• Locate the read-write data area by referring to class AQMDATA. 

The 8087 emulator uses the 8086 microprocessor's interrupts 20 through 3 1 . If the 
program uses any REAL variables, absolute memory locations 50H through 7FH in 

I the 8086 microprocessor's final located module will contain the necessary code for 
these interrupts in the interrupt vector. These memory locations should not be used 
for any other purpose. 

end 

PL/M-86 — 
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RUN-TIME INTERRUPT PROCESSING 



G.1 General Information 

Interrupts can be initialized when the CPU receives a signal on its maskable interrupt 
pin from a peripheral device, or when control is transferred to an interrupt vector by 
the CAUSE$INTERRUPT statement. If the program runs under an operating system 
that traps interrupts, the information in this appendix may not be applicable. 

Note that the CPU does not respond to the interrupt signal unless interrupts are 
enabled. The compiler does not generate any code to enable or disable interrupts at 
the start of the main program. 

If interrupts are enabled and vectored through an interrupt gate, the following actions 
take place: 

1 . The CPU completes any instruction currently in execution. 

2. The CPU issues an acknowledge interrupt signal and waits for the interrupting 
device to send an interrupt number. 

3. The CPU flag register is placed on the stack (occupying two bytes of stack 
storage). 

4. Interrupts are disabled by clearing the IF flag. 

5. Single stepping is disabled by clearing the TF flag. 

6. The CPU activates the interrupt procedure corresponding to the interrupt number 
sent by the interrupting device. 

7. When that procedure terminates, the stack is automatically restored to the state it 
was in when the interrupt was received, and control returns to the point where it 
was interrupted. 



The mechanism for this activation and restoration are described in the following 
sections. If interrupts are vectored through a trap gate, the fourth step is not per- 
formed; if they are vectored through a task gate, all seven steps are replaced by a task 
switch. 
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| G.2 The Interrupt Vector 

If the NOINTVECTOR control is not specified, an interrupt vector entry is automati- 
cally generated by the compiler for each interrupt procedure. Collectively, the inter- 
rupt vector entries form the interrupt vector. If NOINTVECTOR is specified, the 
interrupt vector must be supplied as explained in Chapter 1 1 . 

The interrupt vector is an absolutely located array of POINTER values beginning at 
location 0. Thus the nth entry is at location 4*n and contains the location of the 
procedure declared with the INTERRUPT n attribute. 

Note that the first and second bytes of each entry contain an offset, while the second 
two bytes contain a segment address. The entries are always four-byte pointers, and 
the segment address is always used in transferring to the interrupt procedure, even if 
the program size is SMALL. 

The CPU uses the interrupt vector entry to make a long indirect call to activate the 
appropriate procedure. At this point, the current code segment address (CS register 
contents) and instruction offset (IP register contents) are placed on stack. 

At the point where the procedure is activated, the stack layout is as shown in 
Figure G-l. 

end 

PL/M-86 — 



HIGHER 
LOCATIONS 



X UJ 
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LOWER 
LOCATIONS 







FLAG REG. CONTENTS 


2 BYTES 


RETURN SEGMENT SELECTOR 


PRESENT REGARDLESS OF 
PROGRAM SIZE 


RETURN OFFSET 
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Figure G-I Stack Layout at Point Where an Interrupt Procedure Gains Control 
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— PL/M-286/386 

G.3 The Interrupt Descriptor Table ^ 

The interrupt descriptor table (IDT) contains descriptors that vector interrupts, traps, 
and protection exceptions to their respective handling routines. 

These descriptors are called gates; they can be either interrupt gates, trap gates, or 
task gates. Interrupt gates and trap gates point to a particular entry point in the 
address space of the interrupted user (i.e., to an interrupt procedure). Task gates 
point to an interrupt processing task state segment (TSS). 

The system builder is used to set up the IDT and to assign numbers to vector the 
individual gates to the appropriate interrupt procedure or task. For more information, 
see the system builder user's guide. 

The IDT can hold up to 256 gates. Gates through 31 are reserved for internal use. 

G.3.1 Procedures and Tasks 

For the 80286 microprocessor, when an interrupt is vectored through an interrupt 
gate, all registers must be pushed onto the stack (see section G.4), interrupts are 
automatically saved in the TSS, and the microprocessor's registers are loaded from 
the TSS of the interrupt task. Thus, no explicit register saving is necessary. Interrupts 
are enabled or disabled depending on the setting of the flags in the interrupt task's 
TSS during its execution (unless explicitly changed). This enables the interruption of 
the interrupt task. Note, however, that if the same interrupt that is currently being 
handled occurs, a protection violation will occur. 

Similarly, for the 80386 microprocessor, when an interrupt is vectored through an 
interrupt gate, all registers must be pushed onto the stack (see section G.4), and 
interrupts are automatically disabled. (Interrupts must be explicitly enabled.) The 
interrupt procedure then begins execution. The interrupt procedure ends with an 
IRET instruction that acts as a normal return. Hence, execution starts at the begin- 
ning of a procedure each time it is entered. 

Specific to the 80836 microprocessor, the interrupt process differs for an interrupt 
vectored through a task gate. The registers for the interrupted task are saved in the 
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PL/M-286/386 — 

(continued) 

TSS, and the microprocessor's registers are loaded from the TSS of the interrupt task. 
Thus, no explicit register saving is necessary. Interrupts are enabled or disabled de- 
pending on the flag settings in the interrupt task's TSS during execution of the inter- 
rupt task (unless explicitly changed). This enables interruption of the interrupt task. 
However, a protection violation will occur if an interrupt task is busy and an attempt 
is made to vector through the busy interrupt task. 

For both the 80286 and the 80386 microprocessors, the interrupt task also ends with 
an IRET instruction, but in this case it acts as a task switch, saving the status of the 
outgoing interrupt task in memory. When the task is re-entered, execution continues 
at the first instruction after the IRET instruction. 

end 

PL/M-286/386 — 



G.4 Interrupt Procedure Prologue and Epilogue 

An interrupt procedure begins by declaring its name and its PUBLIC or EXTERNAL 
attribute. The following interrupt procedure declaration is the correct form for 
PL/M-286 and PL/M-386: 

HANDLER: PROCEDURE INTERRUPT PUBLIC i 

For PL/M-86: 

HANDLER: PROCEDURE INTERRUPT ED? EXTERNAL; 

This alerts the compiler to create a code prologue appropriate to a routine that will, in 
general, be invoked by interrupts. 

PL/M-86/286 — 

For the 8086 and the 80286 microprocessors, at the beginning of each interrupt pro- 
cedure, the interrupt procedure prologue inserted by the compiler accomplishes the 
following tasks: 

1. Pushes the CPU registers onto the stack in the following order: AX, CX, DX, 
BX, SP, BP, SI, DI. 

2. Pushes the ES register contents onto the stack. 

3. Pushes the DS register contents onto the stack. 

4. Loads the DS register with a new data segment address taken from the current 
code segment (i.e., the segment containing the interrupt procedure). 
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(continued) 



5. Pushes the BP register contents onto the stack. 



6. Loads the stack marker (BP register) with the address taken from the current 
stack pointer (SP register). 

7. If the procedure has the REENTRANT attribute, space is reserved on the stack 
for any local variables declared in the procedure. 

However, if the procedure is REENTRANT and contains local variables, steps five, 
six, and seven will be replaced by the ENTER instruction. 

end 

PL/M-86/286 



— PL/M-386 

For the 80386 microprocessor, at the beginning of each interrupt procedure, the 
interrupt procedure prologue inserted by the compiler accomplishes the following 
tasks: 

1. Pushes the CPU registers onto the stack in the following order: EAX, ECX, 
EDX, EBX, ESP, EBP, ESI, EDI. 

2. Pushes the ES, FS, GS, and DS register content on the stack. 

3. If the interrupt procedure has the PUBLIC attribute, and if it is exported from a 
subsystem, the contents of the DS register is placed on the stack and is then 
updated to the data segment of the procedure. In addition, ES is set to DS. 

4. The stack marker offset (EBP register contents) is placed on the stack, and the 
current stack pointer (ESP register contents) is used to update the EBP register. 

5. If the procedure has the REENTRANT attribute, space is reserved on the stack 
for any variables declared within the procedure. (This does not include based 
variables, variables with the DATA attribute, or variables with the AT attribute.) 

end 

— PL/M-386 
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NOTE 



The compiler may temporarily use the DS register (and, for the 80386 micro- 
processor, the ES register) in some cases (e.g., string built-ins), but always 
restores it. Take care to note this possibility when writing an interrupt proce- 
dure in assembly language. 

At the point where the interrupt procedure prologue gains control, the stack layout is 
as shown in Figure G-l . 

After the interrupt procedure prologue is executed (at the point where the code 
compiled from the procedure body gains control), the stack layout is as shown in 
Figure G-2. 
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Figure G-2 Stack Layout during Execution of Interrupt Procedure Body 
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The return from the procedure body is called the interrupt procedure epilogue; it 
restores the stack to the state it was in before the interrupt occurred. The interrupt 
procedure epilogue contains the following steps: 

1 . If the compiler has used stack locations for temporary storage or local variables 
during procedure execution, the stack pointer (the SP register for the 8086 and 
the 80286 microprocessors and the ESP register for the 80386 microprocessor) 
is loaded with the current stack marker (the BP register for the 8086 and the 
80286 microprocessors and the EBP register for the 80386 microprocessor) dis- 
carding the temporary storage. 

2. The old stack marker is restored by popping the stored value from the stack into 
the EP or EBP register. 

3 . The old data segment is restored by popping the stored value from the stack into 
the DS register. For the 80386 microprocessor, this step will occur only if the 
procedure has a PUBLIC attribute and it is exported from a subsystem. 

4. For the 8086 and the 80286 microprocessors, the stack is popped into the ES 
register. 

5. For the 8086 and the 80286 microprocessors, the stack is popped into the CPU 
registers in the following order: DI, SI, BP, BX, DX, CX, AX. Note that the SP 
register value is discarded. 

For the 80386 microprocessor, the stack is popped into the CPU registers in the 
following order: EDI, ESI, EBP, ESP, EBX, EDX, ECX, EAX. Note that the 
ESP register value is discarded. 

6. An IRET instruction is executed to return from the interrupt procedure restoring 
the IP or EIP, CS, and the flag register contents from the stack. 

For the 8086 and the 80286 microprocessors, if the procedure is REENTRANT and 
has local variables, steps one and two will be replaced by the LEAVE instruction. 

At this point, the stack has been restored to the state it was in before the interrupt 
occurred, and processing continues normally. 
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PL/M-86 — 

G.5 Writing Interrupt Vectors Separately 

In some cases it may be desirable to write the interrupt vector separately (in PL/M or 
assembly language). Do so by using NOINT VECTOR to prevent generation of an 
interrupt vector by the compiler. Then link separately created interrupt vectors into 
the program. 

Creation of a separate explicit vector requires some care. The @ operator in PL/M 
provides access to a procedure's normal (i.e., called) entry point, not to its interrupt 
entry point. The interrupt entry point first saves the status of the interrupted program 
before invoking the interrupt procedure through its normal entry point. The exact 
length of these operations depend on the compilation options chosen, the attributes of 
the interrupt procedure, and the version of the compiler being used. Use the built-in 
function INTERRUPT$PTR during execution to return the actual interrupt entry 
point. Discussion of this function appears in Chapter 9. 

For example, suppose that two modules for a multimodule program are developed 
separately. Both use interrupt procedures, but when the modules are written the 
assignment of interrupt numbers to the various interrupt procedures has not been 
determined. 

The two modules are therefore compiled with the NOINT VECTOR control. When 
this is done, the n in an INTERRUPT n attribute is ignored; since normally it would 
only be used to put the procedure's entry in the proper location within the interrupt 
vector. 

Later, when the program is combined, a separately created interrupt vector can be 
linked in. Within this interrupt vector, the placement of the entry for a given interrupt 
procedure determines which interrupt number will activate that procedure. 

Similarly, a library of interrupt procedures could all be compiled with NOINT- 
VECTOR. Any program could then have any of these procedures linked in, with a 
separately created interrupt vector. 

Use the built-in procedure SET$INTERRUPT during execution to create the correct 
interrupt vector for each interrupt routine. This procedure is discussed in Chapter 9. 



I 

end 

PL/M-86 
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— PL/M-286/386 

G.6 Interrupt Tasks ^ 

A task on the microprocessor is a single thread of execution; that is, a stream of 
instructions and data with a task state image. The task state image is made up of the 
contents of the task registers, the task's status word, and the virtual locations of the 
task's instructions and data segments. 

Tasks are initiated with a task switch operation. The CPU stores the task state image 
of the outgoing task (held in the processor registers) in memory, and loads the task 
state image of the incoming task into task registers. Because all the registers are 
reloaded and a new address space is entered, it is impossible to jump directly from 
one task to another. 

Interrupt tasks are frequently written as one loop. At the beginning is the code needed 
to initialize the task, followed by the steps needed to handle the interrupt. Call the 
WAIT$FOR$INTERRUPT built-in procedure (see Chapter 10) to generate an IRET 
instruction. When the task is activated again, execution continues at the instruction 
following the IRET, with all the registers unchanged. At the end of the interrupt task, 
use a GOTO statement to loop back to the top of the interrupt task. Thus, an interrupt 
task never terminates, unless an operating system function removes the task. 

Use of the WAIT$FOR$INTERRUPT procedure is demonstrated in the following 
example. This task is designed to handle messages that arrive in pieces, each one 
being preceded by an interrupt. 

TASK : DO 

DECLARE local variables; 

local procedures; 

NEU$riESSAGE: 

CALL INITIALIZE$riESSAGE$PROCESSING; 

DO forever; 

CALL UAIT$FOR$INTERRUPT; 
/* IRET to wait for next interrupt which continues here */ 



Run-Time Interrupt Processing 



G-9 



PL/M-286/386 — 

(continued) 

I CALL PR0CESS$PIECE$0F$r1ESSAGEi 
IF LAST$PIECE$OF$MESSAGE$ THEN DOi 
CALL TERHINATESrlESSAGESPROCESSINGi 
CALL li)AIT$FOR$INTERRUPTi 

/* IRET to wait for start of next message */ 
GOTO NEUSMESSAGE 
■ END i 

ENDi 

I END TASK; 

end 

PL/M-286/386 — 



G.7 Exception Conditions in REAL Arithmetic 

Six exception conditions can occur during normal numeric operations: 

• Invalid operation 

• Denormalized operand 

• Zero divide 

• Overflow 

• Underflow 

• Precision 

These exceptions are discussed in the following sections. In each case, only a few of 
the possible causes are described because most are not likely to occur with PL/M 
usage. To perform sophisticated numeric processing of extreme precision and flexi- 
bility, refer to the microprocessor-specific programmer's reference manual. 

The six exceptions and their default responses are summarized in Table 0-1. 

As the following sections indicate, the masked, default response to most exceptions 
will provide the least abrupt, most appropriate action for PL/M applications. Many 
real math exceptions that occur in other processors will not occur with the numeric 
coprocessor because of the extended range of intermediate results it holds. The soft 
recovery of gradual underflow (described in the denormal exception section) also 
extends the range of permissible execution rather than reporting a hard-failure 
condition. 
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Table G-l Exception and Response Summary 



Exception 


Masked Response 


Unmasked Response 


Invalid 
Operation 


If one operand is NAN, 
return it; if both are NANs, 
return NAN with larger abso- 
lute value; if neither is NAN, 
return indefinite NAN. 


Request interrupt. (Numeric 
coprocessor stack 
unchanged.) 


Zero divide 


Return infinity signed with 
"exclusive or" of operand 
signs. 


Request interrupt. (Numeric 
coprocessor stack 
unchanged.) 


Denormalized 


Memory operand: proceed 
as usual. Register operand: 
convert to valid unnormal, 
then reevaluate for 
exceptions. 


Request interrupt. (Numeric 
coprocessor stack 
unchanged.) 


Overflow 


Return properly signed 
infinity. 


Register destination: adjust 
exponent, store result, (see 
note) request interrupt. 
Memory destination: request 
interrupt. 


Underflow 


Denormalize result. 


Register destination: adjust 
exponent, store result, (see 
note) request interrupt. 
Memory destination: request 
interrupt. 


Precision 


Return rounded result. 


Return rounded result, 
request interrupt. 



Note: On overflow, 24,576 decimal is subtracted from the true result's exponent. This forces the 
exponent back into range and enables a user exception handler to ascertain the true result from 
the adjusted result that is returned. On underflow, the same constant is added to the true result's 
exponent. 



Programmers who use the recommended setting of the REAL mode word (see Chap- 
ter 10) need to handle only the invalid exception. Study of the other exception condi- 
tions is advised, however, to gain a general understanding of their use. 

G.7.1 Invalid Operation Exception 

This exception generally indicates a program error. It could be caused by referencing 
an uninitialized REAL variable or by referencing a location that does not contain a 
REAL value (as might occur with an out-of-range subscript for a REAL array). 
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Attempting to take the square root of a negative number or to store a number too large 
for integer format would also generate this exception. 

Another interpretation of this exception is stack error. This may be caused by failing 
to restore the math unit status before returning from an interrupt routine that had 
saved the status. Another cause is the generation of more than eight intermediate 
results during REAL arithmetic, which can arise if REAL procedure function calls 
are nested too deeply. The compiler ensures that no single procedure does this, but 
cannot check what may occur only at run time. This exception can also occur when 
REAL functions (typed procedures) are used as operands within longer REAL ex- 
pressions. For example: 

DELTA51 = ALPHA * (BETA/GAMMA) + CHI (PSI-, RH0-, PI) 

where all these names are typed REAL and CHI is some previously declared REAL 
function having three parameters. 

The following is less likely to cause an exception condition: 

EPS = CHI CPSI-i RH0-, PI) 

DELTA*1 = ALPHA * ( BET A/GArMI A ) + EPS 

because all REAL arithmetic is performed using the numeric coprocessor's stack, 
which has eight registers. The first seven REAL parameters supplied in procedure 
calls are placed on this stack. If the procedure is typed (i.e. , invoked as a function), it 
can be imbedded as one operand within a longer REAL expression. 

Because the evaluation of such an expression also involves the use of this stack for 
prior and subsequent arithmetic operations, stack overflow may occur. This overflow 
amounts to unpredictable destruction of original parameters or intermediate results. It 
becomes more likely as the complexity of REAL expressions containing REAL func- 
tions is increased. Thus, it is safer to use an assignment statement first to store the 
function's value in a real variable; then use that variable in the larger expression. 

If stack error might apply, modify the code for the effected procedures to call the 
built-in procedures SAVE$REAL$STATUS and RESTORE$REAL$STATUS as their 
first and last operations, respectively. 

The masked (default) response is to set the result to one of the special bit patterns 
called Not-A-Number (NANs), usually the indefinite value, the smallest NAN repre- 
sentable in the specified precision. It also sets bit of the REAL error byte. 

If bit of the REAL mode word is (invalid exception unmasked), an interrupt 
occurs, transferring control to the user-written interrupt handler. 
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G.7.2 Denormal Operand Exception 



This condition arises when numeric operations have resulted in a number whose 
exponent is literally zero and whose significand is non-zero, or have resulted in a 
number whose significand does not begin with a one. Denormals usually arise in 
response to masked underflow. Gradual underflow is the masked, default response to 
underflow. A small denormal added to a large normal REAL number can give an 
acceptable, in-range answer if the denormal exception is masked. In practice, denor- 
mals are very rare since intermediate results are kept in temporary real format (15-bit 
exponent). 

This condition causes bit 1 of the REAL error byte to be set to 1 . If bit 1 of the REAL 
mode word is 1, the response described previously occurs. If bit 1 is 0, an interrupt 
occurs, transferring control to the user-written interrupt handler. 

G.7.3 Zero Divide Exception 

This condition arises when in the course of some REAL computation a divisor turns 
out to be zero. The masked response, when bit 2 of the REAL mode word is 1, is to 
return infinity appropriately signed. If bit 1 is 0, an interrupt occurs, giving control 
to the user- written interrupt handler. In either case, bit 2 of the REAL error byte is 
set to 1 . 

G.7.4 Overflow Exception 

This error occurs when a real result is too large for the format in use. For assigning to 
REAL scalar types, it occurs if the result is greater than about 3.37 x 10**38. For 
intermediate REAL computations, it occurs if the result is greater than about 
10**4932. The overflow exception can arise during assignment, addition, subtrac- 
tion, multiplication, division, or conversion to integer. 

The masked, default response (bit 3 of REAL mode word = 1) is to return infinity 
(signed if affine mode is set) and set bit 3 of the REAL error byte to 1 . Unmasked 
overflow must go through a user-written interrupt handler. 

G.7.5 Underflow Exception 

Underflow exception is caused by an exponent too small for the format in use. For 
REAL assignments, it occurs if the exponent is less than — 127; and for intermediate 
results if the exponent is less than — 16383. Underflow can be caused by the same 
type of REAL operations as overflow. 
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The masked, default response (bit 4 of REAL mode word = 1) is to use the denormal 
number created by adjusting the very small result. It adjusts the significand, moving 
significant digits off to the right and raising the exponent until the latter becomes non- 
zero. For example, with single precision values, a 24-bit significand of .01 with an 
exponent of zero implies the number 1 x 2** — 129 because a zero exponent in this 
format means — 127. If the denormal exception is masked, this number would be 
adjusted into a significand of .001 with an exponent of 1 (i.e., 0.001 x 2**— 126), 
prior to operation. This number would then be available for use in subsequent REAL 
operations that might yield valid results. Zero is returned if it is the rounded result. 
Bit 4 of the REAL error byte is set to 1 . Unmasked underflow must go through a 
user-written interrupt handler. 

G.7.6 Precision Exception 

This error occurs when the result of an operation is inexact (i.e., rounded) or when 
an overflow exception occurs. No special action is performed by a masked response 
(bit 5 of REAL mode word = 1) other than setting bit 5 of the REAL error byte. 
Unmasked response is as chosen by the user. 

G.8 Writing a Procedure to Handle REAL Interrupts 

This section partially summarizes the information pertaining to interrupts, floating- 
point usage, and procedures. (Additional facilities for handling REAL interrupts may 
be provided by the operating system, or can be performed with the system builder.) 

An interrupt-handling procedure for PL/M-286 may, for example, begin as follows: 
HANDLER: PROCEDURE INTERRUPT PUBLICi 

If HANDLER will do any REAL arithmetic or assignments, its first executable state- 
ments should be of the form: 

ERR5INF0 = GET$REAL$ERRORi /* must declare ERR$INF0$ BYTE earlier */ 
or: 

CALL SAVE$REAL$STATUS OLocal_Save_Area) ; /* also declare earlier */ 

Each procedure clears the error byte. The latter procedure also clears out the REAL 
stack. Thus, after either procedure is used, the REAL error byte no longer contains 
the flagged cause of the exception condition that invoked HANDLER. 

Using SAVE$REAL$STATUS is a way of avoiding possible stack errors from cumu- 
lative usage. This enables errors in HANDLER to be detected independently of 
the originating exception condition. It also enables HANDLER to restore the state 
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of the interrupted procedure despite HANDLER'S own use of the REAL facility. 
SAVE$REAL$STATUS also makes available all the information regarding the state 
of the numeric coprocessor exceptions, stack, and operations, as shown in the follow- 
ing paragraph. 

Thus, the beginning of a typical routine for the 80286 microprocessor to handle 

REAL exception conditions could look like this: 

HANDLER: PROCEDURE INTERRUPT PUBLIC"-, 

DECLARE ERR5INF0 BYTE'-, 

DECLARE LOCAL$SAVE$AREA ( m ) BYTEi 

ERR5INF0 = GET$REAL$ERRORn 



or, to perform extensive manipulations on the save area, declare a structure permit- 
ting access to the save area's component parts by name and/or byte, as follows: 
HANDLER: PROCEDURE INTERRUPT PUBLICi 

DECLARE ERRSINFO BYTE; 
DECLARE SAVESAREA STRUCTURE ( 



CONTROL(S) 


BYTE-, 


ST ATUS ( 2 ) 


BYTE-, 


TAG 


WORD i 


INSTR_0FF 


U0RD-, 


INSTR—SEL 


SELECTOR-, 


0PERAND_0FF 


UORD i 


OPER AND_SEL 


SELECTOR-, 


STACK_T0P(S) 


UORD -, 


STACK_0NE(S) 


UORD -, 


STACK_TU0 (5) 


UORD -, 


STACK_3 (S) 


U0RD-, 


STACKJ (5) 


UORD -, 


STACK_S (S) 


UORD -i 


ST ACK_b (S) 


UORD-, 


STACK_7 (5) 


UORD ) i 



CALL SAVE$REAL$STATUS ( 3SA VE_ARE A ) ^ 
ERR5INF0 = SAVE_ARE A -STATUS(D)i 

NOTE 

To make use of the TAG word, use the masks and shifts to access the 
individual fields shown in Figure G-3. 

Call either the SAVE$REAL$STATUS procedure or the GET$REAL$ERROR func- 
tion, but not both. If the extra information gained by the SAVE is not needed (i.e., 
only the exceptions are needed), use the GET$REAL$ERROR function. If both are 
called, the second call will produce incorrect results. 
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TAG(7| 
I 



TAG(6) 
I 



TAG(S) 
I 



TAG(4) 
I 



TAG(3) 
__l 



TAG(2) 
I 



TAGU) 
I 



TAG(O) 
I 



Tag values: 

00 = Valid (Normal or Unnormal) 

01 = Zero (True) 

10 = Special (Not-A-Number. «... or Denormal) 

11 = Empty 



Figure G-3 Tag Word Format 
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The rest of HANDLER can perform any actions deemed appropriate. This is an 
application dependent decision. Among the possibilities: 

• Incrementing an exception counter for later display 

• Printing diagnostic data (e.g., the contents of SAVE$AREA) 

• Aborting further execution of the calculation causing exception 

• Aborting all further execution 

The format of the LOCAL_SAVE_AREA as it is filled by the save procedure is 
shown in Figures G-4 and G-5. 

The final action prior to returning (if desired) to the interrupted procedure is to 
restore the status of the REAL math unit: 

CALL RESTORE$REAL$STATUS OL0CAI SAVE_AREA) '-, 

However, if GET$REAL$ERROR is not used prior to the SAVE$REAL$STATUS 
call, the local save area will contain the original contents of the error byte. Under 
these circumstances, first clear the lower byte of the saved status word before the 
RESTORE statement to avoid retriggering the same exception that invoked 
HANDLER in the beginning. 



To do so, use a command of the form: 
L0CAI SAVE_AREA (2) = D =■ 

or: 



/* should precede restore */ 



SAVE_AREA -STATUS (□) 



On 
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INCREASING ADDRESSES 



INSTRUCTION 
POINTER 



OPERAND 
POINTER 



TOP STACK , 
ELEMENT:ST "\ 



NEXT STACK 
ELEMENT:ST(1) 



LAST STACK 
ELEMENT:ST(7) 



CONTROL WORD 



STATUS WORD 



TAG WORD 



OP 15-0 



SIGNIFICAND 15-0 



SIGNIFICAND 31-16 



SIGNIFICAND 47-32 



SIGNIFICAND 63-48 



EXPONENT 14-0 



SIGNIFICAND 15-0 



SIGNIFICAND 31-16 



SIGNIFICAND 47-32 



SIGNIFICAND 63-48 



EXPONENT 14-0 



SIGNIFICAND 15-0 



SIGNIFICAND 31-16 



SIGNIFICAND 47-32 



SIGNIFICAND 63-48 



EXPONENT 14-0 



* 
+ 2 
+ 4 
+ 6 
+ 8 
' 10 

- 12 
14 

- 16 

- 18 

- 20 
22 
24 
26 

■ 28 
30 
32 

84 
86 
88 

• 90 

* 92 



NOTES: 
S = Sign 

BIT OF EACH FIELD IS RIGHTMOST. LEAST SIGNIFICANT BIT OF CORRESPONDING 
REGISTER FIELD. 

BIT 63 OF SIGNIFICAND IS INTEGER BIT (ASSUMED BINARY POINT IS IMMEDIATELY 
TO THE RIGHT). 
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Figure G-4 Memory Layout of the REAL Save Area for the 8086 and the 80286 
Microprocessors, and the 8087 and the 80287 Numeric Coprocessors 
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31 16 15 





RESERVED 


CONTROL WORD 







RESERVED 


STATUS WORD 


■ 4 




RESERVED 


TAG WORD 


8 


Instruction \ 


INSTRUCTION POINTER OFFSET 


12 


Pointer | 


RESERVED 


INSTR. PTR SELECTOR 


■ 16 


Operand \ 


OPERAND OFFSET 


20 


Poinier j 


RESERVED 


OP SELECTOR 


24 


I 

Top 1 


ST(O) SIGNIFICAND 31-0 


• 28 


Slack ] 
Element \ 


ST(0) SIGNIFICAND 63-32 


32 


ST 


ST| 11 SIGNIFICAND 15-0 


S 


STIOI EXPONENT 


■ 36 


Ne»t 1 
Stack 

Element | 


ST(1) SIGNIFICAND 47-16 


- 40 


S 


STI1) EXPONENT 


ST(1) SIGNIFICAND 63-48 


44 


ST[1) 






Neitto | 
Last 


ST(6) SIGNIFICAND 31-0 


88 


Element I 

STI6I 


ST(6I SIGNIFICAND 63-32 


92 


Last I 


ST(7) 15-0 


S 


ST(6) EXPONENT 


96 


Stack ) 
Element: ] 




ST(7) 




47-16 


100 


ST(7) 


S 


ST(7) EXP 


ST(7) 63-48 


- 104 
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Figure G-5 Memory Layout of the REAL Save Area in Protected Mode for the 
80386 Microprocessor 
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H RUN-TIME SUPPORT FOR 
PL/M APPLICATIONS 

In addition to tools that support the software development process, Intel provides run- 
time support for application programs. 

H.1 Numeric Coprocessor Support Libraries 

Two libraries contained in the 8087 numeric coprocessor support library are of use to 
PL/M programmers: DCON87.LIB and CEL87.LIB. DCON87.LIB aids in number 
format translation (e.g., from binary to ASCII). CEL87.LIB is a common elemen- 
tary function library that provides an assortment of functions involving floating-point 
numbers, such as rounding. 

Three libraries contained in the 80287 numeric coprocessor support library are of use 
to PL/M programmers: CEL287.LIB, DC287.LIB, and EH287.LIB. CEL287.LIB 
includes common elementary functions (logarithmic, exponential, trigonometric, hy- 
perbolic, etc.). DC287.LIB converts floating-point representations from ASCII deci- 
mal format to internal binary format, and vice versa. DC287.LIB is used by 
PL/M-286 and PL/M-386 programs to perform type conversions. EH287.LIB in- 
cludes floating-point exception-handling procedures. 

For additional information on the libraries contained with both the 8087 and the 
80287 numeric coprocessors, see the numeric coprocessor reference manual. 

H.2 PL/M Support Libraries 

The PL/M libraries contain connection procedures and complex built-ins written in 
assembly language. The following library modules are provided in the PL/M 
libraries: 

• PL/M-86 and PL/M-286 — LQ_DWORD_DIVIDE and 

LQ_DWORD_MULTIPLY 

• PL/M-386 — INTERFACE286_FAR, 

INTERFACE286_NEAR, 
LQ_DWORD_DIVIDE, 
LQ_DWORD_MULTIPLY, MOVBIT, 
MOVRBIT, SCANBIT, and SCANRBIT. 
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INDEX 

A 

ABS function, 9-21, 9-22 
Access 

Or lock shared memory, 9-39 thru 9-4 1 

Output port built-in functions, 10-7, 10-8 
ADDRESS function, 9-21 
Address 

Register, segmentation controls, 13-3 thru 13-7 

Translation, see Type conversion 

Unknown, 3-26 thru 3-29 
ADJUST$RPL, 10-20, 10-21 
Algebraic-shift functions, 9-25 
Apostrophe in string, to include, 2-6 
Arithmetic 

Floating-point, 3-19 thru 3-21 

Unsigned/signed/floating-point — rules for choice, 5-15 thru 5-20 
Arithmetic, REAL, Appendix G 
Arrays, 3-1, 3-2, 3-9, 4-1 thru 4-7 

Built-in, 10-16, 10-17 

Elements, return number or size, subscripts, 9-2 thru 9-4 
ASCII 

Characters used in PL/M, 2-1, 2-2, Appendix E 
Characters and hex values, Appendix E 
ASM 

Interface, 11-20 thru 11-23 

Subroutines, to call from a PL/M program, see Appendix F 
Assignment statement, 5-22 thru 5-28 
AT attribute, 3-28 thru 3-31 
Attributes 

EXTERNAL, 7-5 thru 7-11, 8-9, 8-10, 8-15 
INTERRUPT, 8-11 thru 8-13 
PUBLIC, 7-5 thru 7-11, 8-9, 8-10 

PUBLIC/EXTERNAL, and subsystem communication, 13-14, 13-16 
REENTRANT, 8-10, 8-14, 8-15 
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B 

Based variables, 3-26 thru 3-29 
Binary 

Conventions, 2-5 

Scientific notation, 3-20, 3-21 
Binding program modules, see Combining program modules 
Bit 

Lock functions, 9-40, 9-41 
Manipulation functions and procedures, 9-36 
Patterns, to move right or left, 9-22 thru 9-26 
Blanks, 2-2, 2-3 

BLOCKINHWORD, BLOCKINPUT, BLOCKINWORD procedures, 10-9 
BLOCKOUTHWORD, BLOCKOUTPUT, BLOCKOUTWORD procedures, 10-10 
Blocks, 1-2, 7-1 thru 7-12 

inclusive/exclusive extent, 7-1 thru 7-4 
BUILD$PTR function, 9-42, 9^3 
Built-in arrays, 10-16, 10-17 

Built-in functions, procedures, variables, 1-4, Chapters 9, 10 
BYTE type conversions, 9-14 thru 9-18 

c 

CALL, 6-15, 8-1 thru 8-7, 8-13, Chapters 9, 10 
Calling 

ASM subroutines from a PL/M program, Appendix F 
C programs from PL/M, F-13, F-14 
Other files, 11-19, 11-20 

Procedures in other languages, 11-12, 1 1-20 thru 11-23 
Calls, long, short, and indirect, 8-7 
CARRY flag, 10-2 thru 10-5 
CASE, DO block, 6-1, 6-4, 6-5 
Casting — See Type conversion 
CAUSESINTERRUPT statement, 8-13, 10-1 
Character set, 2-1 thru 2-4, Appendix E 
Character strings, 2-6, 2-7 

CLEAR$TASK$SWITCHED$FLAG built-in procedure, 10-17 

Closed subsystems, 13-2, 13-13, 13-14 

CMP (compare strings) functions, 9-29, 9-30 

CODE control, 11-3, 11-11, 11-15, 11-44 

Code listing example, 11-64 

Combining program modules, 1-1 

Command tail errors, 14-20 
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Index 



Comments, 2-7 
COMPACT 

Control, 11-5, 11-7, 11-8, 11-10 thru 15, 11-49 thru 11-52 

Segmentation control, Chapter 13 
Compare string functions, 9-30 
Comparison, invalid with relational operators, 5-14 
Compatibility of various versions of PL/M, Appendix D 
Compilation summary listing example, 11-67 
Compiled module, 11-7 thru 11-9 

Compiler invocation, 1-5, 1-6 (See also supplements for supported host systems.) 

Compiler controls. Chapter 1 1 

Compiler failure errors, 14-21, 14-22 

Concatenate functions, 9-26 

COND control, 11-3, 11-12, 11-15, 11-16, 11-44 

Conditional statements, 11-17 thru 1 1-19 

Constants, 2-4 thru 2-6, 5-1 thru 5-3 

Control 

Errors, 14-20 

Line, 11-1 

CONTROUREGISTER built-in array, 10-16 
Conversions, Chapter 9 
Cross-reference listing example, 1 1-66 

D 

Data attribute declaration, 3-3 

Data types, 3-14 thru 3-26 

DEBUG control, 11-3, 11-7, 11-16, 11-17 

DEBUG$REGISTER built-in array, 10-17 

DEC built-in function, 10-4, 10-5 

Decimal 

Adjust, 10-4, 10-5 

Conventions, 2-5 

Numbers, 2-6 
Declarations 

LITERALLY, 3-11, 3-12 

Statements, 1-3 

Types of, 3-10 thru 3-13 
DECLARE statement, 3-1 thru 3-5 
Delay, to cause, 9-38 

Differences among PL/M-86, -286, and -386, Appendix D 
Dimension specifier, 4-1 
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Direct recursion, 8-14, 8-15 

DISABLE statement, 8-11, 10-1 

Division by two, 9-24, 9-25 

DO block and statement, 1-2,1-3,6-1 thru 6-9 

Dollar sign ($), 2-3,2-4, 11-1 

DOUBLE function, 9-14 thru 9-16 

E 

EJECT control, 11-3, 11-11, 11-17 

ELSE control, 11-3, 11-12, 11-17 thru 11-19 

ELSEIF control, 11-3, 11-12, 11-17 thru 11-19 

Embedded assignment statement, 5-27, 5-28 

ENABLE statement, 8-11, 10-1 

END statement, 1-2, 6-10 

ENDIF control, 11-3, 11-12, 11-17 thru 11-19 

Error, masked and unmasked, 10-22 

Error messages, Chapter 14 

Evaluation of expressions, 5-11 thru 5-13 

Executable statements, 1-4 

Exponents, G-13, G-14 

Exporting procedures, 13-18 thru 13-21 

Expressions, 1-5, 5-1 thru 5-28 

Extended segmentation models, Chapter 13 

EXTERNAL attribute, 7-5 thru 7-11, 8-9, 8-10, 8-15 

EXTERNAL/PUBLIC attributes and subsystem communication, 13-14, 13-16 

F 

File 

Include, examples, Chapter 12 

Inclusion with compiler controls, 11-12 

To call, 11-19, 11-20 
File, compiler-generated object, 1 1-7 thru 1 1-10 
Find element functions, 9-30, 9-31 
Find string mismatch functions, 9-31 
Figures, list of, xiv, xv 
FIX function, 9-18 
Flags, hardware, 10-2 thru 10-4 
FLAGS function, 10-5, 10-6 
FLOAT function, 9-17 



Floating-point 
Arithmetic, 3-19 thru 3-21 
Constants, 2-5 

Libraries, linkage specifications, F-14 thru F-16 

Rules for choice, 5-15 thru 5-20 
Flow of control, 6-1 thru 6-15 
Formal parameters, 8-2 thru 8-4 
Function reference, 8-4, 8-6 
Functions, built-in, Chapters 9, 10 

G 

GDTR register, 10-11, 10-12 
GET$ACCESS$RIGHTS function, 10-19 
GET$REAL$ERROR function, 10-26 
GET$SEGMENT$LIMIT function, 10-19 
Global descriptor table register, 10-11, 10-12 
GOTO statement, 6-14, 6-15 

Restrictions, 7-7 thru 7-12 

To exit procedure, 8-8 
Grammar, Appendix C 

H 

HALT statement, 8-12, 10-2 
Hardware, Chapter 10 
Hexadecimal, conventions, 2-5 
HIGH function, 9-14 thru 9-16 

I 

I/O 

Errors, 14-21 

Hardware, 10-6 thru 10-10 

Support, 1-5 
IABS function, 9-22 
Identifiers, 2-4 

Predeclared, A-l thru A-3 
IDT, G-3 

IDTR register, 10-13, 10-14 
IF control, 11-3, 11-12, 11-17 thru 11-19 
IF/ELSE/ELSEIF/ENDIF controls, 11-17 thru 11-19 
IF/THEN/ELSE statement, 6-10 thru 6-14 
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INCLUDE 

Control, 11-3, 11-12, 11-19, 11-20 

File examples, Chapter 12 
Initialization, 3-5 thru 3-9 

Attribute (DATA/INITIAL) declaration, 3-3, 3-6 
INIT$REAL$MATH$UNIT built-in procedure, 10-25 
INPUT, INHWORD, INWORD functions, 10-7 
Input/Output support, 1-5 
Instruction code, 11-8 
INT function, 9-18 

INTERFACE control, 11-3, 11-7, 11-12, 11-20 thru 11-23 
Interfacing with other languages, 1 1-20 thru 1 1-23 
Interrupt 
Descriptor table (IDT), G-3 

Register, 10-13, 10-14 
Mechanism, to enable or disable, 10-1 
Procedure 
And stack size, 1 1-10 
To activate with CALL statement, 8-13 
To create, G-4 thru G-8 
Processing, 10-27, 10-28, Appendix G 
Software, to generate, 10-1 
Vector, to create, 9-41, 11-24 
INTERRUPT attribute, 8-11 thru 8-13 
INTERRUPTSPTR procedure, 9-42 
Interrupt-related procedures, 9-4 1 , 9-42 
INTVECTOR control, 11-6, 11-7, 11-24 
Invocation 
Compiler, 1-5 

Command and subsystem definitions, 13-18 
IRET instruction, to generate, 10-27, 10-28 
Iterative DO block, 6-2, 6-7 thru 6-9 

K 

Kanji character set, 2-1, 2-6, 2-7 
Keywords, A-l thru A-3 

L 

Label declarations, 3-1,3-13 

Label scope, 7-7 thru 7-12 

Languages interface, 11-12, 11-20 thru 11-23 



LARGE 

Control, 11-5, 11-7, 11-8, 11-10 thru 11-15, 11-54 thru 11-56 

Segmentation control , Chapter 1 3 
LAST function, 9-3 
LDTR register, 10-14 

LEFTMARGIN control, 11-3, 11-6, 11-24, 11-25, 11-44 
LENGTH function, 9-2, 9-3 
Libraries, Appendix H 
Limits, Appendix B 

Linkage attribute (PUBLIC/EXTERNAL) declaration, 3-3, 3-6 
Linkage specifications for floating-point libraries, F-14 thru F-16 
Linking program modules, see Combining program modules 
Linking to modules written in other languages, Appendix F 
LIST control, 11-3, 11-11, 11-25, 11-44 
Listing 

Code example, 11-64 

Compilation summary, 1 1 -67 
LITERALLY declarations, 3-11, 3-12 
Local descriptor table register, 10-14 
LOCALSTABLE variable, 10-14 

Location reference, 3-23 thru 3-25, 3-28, 3-29 thru 3-31 
LOCKSET function, 9-39, 9-40 
Logical-shift functions, 9-24 
Long 

Calls, 8-7 

Pointer, 11-23 
Loops, DO, 6-2 
LOW function, 9-14 thru 9-16 
Lowercase characters, 2- 1 

M 

Machine overflow, 11-41 
Machine status register, 10-15 thru 10-17 
MACHINE$STATUS built-in variable, 10-15 
Mask, 10-21 
Masked 
Error, 10-22 

Underflow in REAL arithmetic, G-13 
Math facility, 10-21 thru 10-28 
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MEDIUM 

Control, 11-5, 11-7, ll-10thru 11-15, 11-52 thru 11-54 
Segmentation control. Chapter 13 
Memory 

8086 microprocessor memory reference, 9-38 

Insufficient 
Errors, 14-21 
Warning, 14-22 

Partitions, segmentation controls, 13-3 thru 13-7 

Shared, to access or lock, 9-39 thru 9-41 

To reference, 9-38 
MEMORY predefined array, 9-38 
Messages, Chapter 14 
MINUS operator, 5-7, 10-3 

MOD86/MOD 186 controls, 11-6, 11-7, 11-25, 11-26 

Module, 1-3, 1-6, 1-7, 11-7 thru 11-9 

MOVE, MOVHW, MOVW procedures, 9-27 

MOVRB, MOVRHW, MOVRW procedures, 9-29 

MOVBIT procedure, 9-35, 9-36 

MOVE procedure, 9-37 

Move bit patterns right or left, 9-22 thru 9-26 

MOVR procedure, 9-28, 9-29 

MSW register, 10-15 thru 10-17 

Multiplication by two, 9-24, 9-25 

N 

Names, symbolic, 3-1 
Naming, 2-4 

Labels, 3-12, 3-13 

Procedures, 3-14 
Nested 

Blocks, 7-1 thru 7-12 

DO blocks, 6-3 

IF/THEN/ELSE statements, 6-1 1 thru 6-13 

Structures, 4-5, 4-6 
Nesting limits, see Appendix B 
NIL function, 9-44 

NOCODE control, 11-3, 11-11, 11-15, 11-44 
NOCOND control, 11-3, 11-12, 11-15, 11-16, 11-44 
NODEBUG control, 11-3, 11-7, 11-16, 11-17 
NOINTVECTOR control, 11-6, 11-7, 11-24 



NOLIST control, 11-3, 11-11, 11-25, 11-44 
NOOBJECT control. 11-4, 11-7, 11-26 
NOOVERFLOW control, 11-4, 11-7, 11-35, 11-41, 11-44 
NOPAGING control, 11-4, 11-11, 11-42, 11-43 
NOPRINT control, 11-4, 11-11, 11-43 
NOSYMBOLS control, 11-5, 11-11, 11-57 
Notation, scientific binary, 2-6, 3-20, 3-21 
NOT YPE control, 11-6, 11-7, 11-58 
NOXREF, 11-6, 11-11, 11-61 
Null statement, 6-5 

Number base (binary, decimal, hexadecimal, and octal), 2-5 
Numeric constant, 5-1 
Numeric coprocessor 

Libraries, Appendix H 

Linkage specifications, F-14 thru F-16 

o 

Object 

Code optimization, 11-27 thru 11-41 

File, 11-7 thru 11-10 

Scope, 7-1, 7-2, 7-5 thru 7-8 
OBJECT control, 11-4, 11-7, 11-26 
Octal, conventions, 2-5 
OFFSET function, 9-22, 9-43 
Open subsystems, 13-2, 13-12, 13-13 
Operands, 5-1, 5-4 
Operators, 2-3, 5-5 thru 5-16 

. (dot) operator, 3-25 

@, 3-23 thru 3-25, 3-28, 3-29 

MINUS, 10-3 

PLUS, 10-3 

Precedence, 5-11 

Relational, 5-14 
Optimization 

Effect on hardware flags, 10-2, 10-3 

Examples, 11 -33 thru 11-41 

Optimizing code, Chapter 13 
OPTIMIZE control, 11-4, 11-7, 11-27 thru 11-41 
OUTPUT, OUTHWORD, OUTWORD functions, 10-7 
OVERFLOW control, 11-4, 11-7, 11-35, 11-41, 11-44 
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PAGELENGTH control, 11-4, 11-11, 11-42 
PAGE WIDTH control, 11-4, 11-11, 11-42 
PAGING control, 11-4, 11-11, 11-42, 11-43 
Parameters, actual and formal, 8-2 thru 8-6 
PARITY flag, 10-3 

Peripheral interrupt procedures, 8-11 thru 8-13 
PL/M-86 interrupt-related procedures, 9-41, 9-42 
PL/M-386 

Program example. Chapter 12 

Subsystems example, 13-21 thru 13-23 

WORD32/WORD16 mapping, 9-45, 9-46, 10-28, 10-29 
PLUS operator, 10-3 
Pointer 

Passing restrictions, SMALL segmentation control, 13-10, 13- 

Placement, segmentation controls, 13-3 thru 13-7 

Restrictions, 11-46, 11-47 

Values, segmentation controls, 13-3 thru 13-7 
Pointer data type, 3-17, 3-21 thru 3-25 
POINTER 

Function, 9-22 

Manipulation, built-in functions, 9-42 thru 9-45 
Predeclared identifiers, Appendix A 
PRINT control, 11-4, 11-11, 11-43 
Printed output, compiler controls to control, 11-11 
Privilege level, to adjust, 10-20, 10-21 
Procedures, 8-1 thru 8-14 

Activation, 8-5 

Body, example, 8-8 

Built-ins, Chapters 9, 10 

CALL statement, 8-1 thru 8-7, 8-13 

Calling procedures in other languages, 1 1-20 thru 1 1-23 

Calls, long, short, and indirect, 8-7 

Declaration, 1-2, 3-14, 8-1 thru 8-5 

Definition, 8-1 
Blocks and statements, 1-3 

Direct recursion, 8-14, 8-15 

Exit from, 8-8 

EXTERNAL attribute, 8-9, 8-10, 8-15 
Function reference, 8-4, 8-6 
Indirect activation, 8-6, 8-7 



Indirect recursion, 8-14, 8-15 
Intermodule reference, 3-14 
Interrupt and stack size, 1 1-10 
INTERRUPT attribute, 8-1 1 thru 8-13 
Naming, 3-14 

PUBLIC attribute, 8-9, 8-10 
Read string, 10-8, 10-9 
Reentrant 

And stack size, 11-10 

To declare, 3-1 
REENTRANT attribute, 8-10, 8-14, 8-15 
RETURN statement, 8-8 
Scope, 8-2 
Stack section, 1 1-10 
To activate, 8-5 thru 8-7 

Indirectly, 8-6, 8-7 
To exit, 8-8 
Typed, 8-4 thru 8-8 
Untyped, 8-4 thru 8-9. 8-11 
Using based variables, 8-9 

WAIT$FOR$INTERRUPT, example of use, G-8, G-9 
Program 

Example, 1-5 thru 1-9, Chapter 12 
Listing example, 1 1-62 thru 1 1-67 
Management for large programs, see Chapter 13 
Modules 
Compiled, 11 -7 thru 11-9 

To bind or link, see Combining program modules 

Segmentation, Chapter 13 

Speed, to enhance, Chapter 13 

Structure, 1-2, 1-3 

Structuring, Chapter 13 
Protection architecture of the microprocessor, to access, 10- 10 thru 10-21 
PUBLIC attribute, 7-5 thru 7-11, 8-9, 8-10 

PUBLIC/EXTERNAL attributes and subsystem communication, 13-14. 13-16 

R 

RAM control, 11-5, 11-7, 11-12 thru 11-15, 11-43, 11-44 
Read string procedure, 10-8, 10-9 
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REAL 
Arithmetic, Appendix G 
Error byte, 10-21, 10-22 
Exception conditions example, G-15 thru G-19 
Function, 9-21 

Interrupt procedures, G-14 thru G-19 
Math facility, 10-21 thru 10-28 

Linkage specifications, F-14 thru F-16 
Mode word (or mask), 10-21, 10-23 
Stack, 10-21 

Status, to save and restore, 10-25 thru 10-27 

To INTEGER conversion, 9-17 
Real number data type, 3-17, 3-19 thru 3-21 
Recursion, direct and indirect, 8-14, 8-15 
REENTRANT attribute, 8-9, 8-14, 8-15 
Reentrant procedures and stack size, 11-10 
Reference 

Array and structure elements, 4-6, 4-7 

Function, 8-4, 8-6 
Register 

Addresses, segmentation controls, 13-3 thru 13-7 
Hardware, 10-5, 10-6 
Usage, F-7 thru F-9 

Used to hold simple data types, F-10, F-l 1 
Requested privilege level, to adjust, 10-20, 10-21 
Reserved words, A- 1 thru A-3 
RESET control, 11-5, 11-12, 11-45, 11-46 
RESTORE control, 11-5, 11-12, 11-44 
Restore REAL status, 10-25 thru 10-27 
RESTORE$GLOBAL$TABLE built-in procedure, 10-12 
RESTORE$INTERRUPT$TABLE built-in procedure, 10-14 
RESTORE$REAL$STATUS built-in procedure, 10-27 
RETURN statement, 6-15, 8-8 
ROL function, 9-22, 9-23 

ROM control, 11-5, 11-7, 11-8, 11-12 thru 11-15, 11-43, 11-44 

ROR function, 9-22, 9-23 

Rotation functions, 9-23, 10-3, 10-4 

Rounding, 10-24 

RPL, to adjust, 10-20, 10-21 

Run-time interrupt processing, Appendix G 

Run-time support libraries, Appendix H 
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s 

SAL function, 9-24, 9-25 

Sample PL/M program. Chapter 12 

SAR function, 9-24, 9-25 

SAVE$GLOBAL$TABLE built-in procedure, 10-12 
SAVE$INTERRUPT$TABLE built-in procedure, 10-13 
SAVE$REAL$STATUS built-in procedure, 10-26. 10-27 
Scalars, 4-1 

Return size, 9-4 

Variable, 3-1 
SCANBIT function, 9-36 
Scientific notation, 2-6, 3-20, 3-21 
SCL built-in function, 10-3, 10-4 
Scope, 7- 1 thru 7-12 

Of a procedure, 8-2 
SCR built-in function, 10-3, 10-4 
Segment (hardware) information, 10-17 thru 10-20 
Segmentation, extended, Chapter 13 
SEGMENT$READABLE function, 10-20 
SEGMENT$WRITABLE function, 10-20 
Selector data type, 3-25, 3-26 
SELECTOR 

Function, 9-22 

Manipulation built-in functions, 9-42 thru 9-45 
SELECTORSOF built-in function, 9-43 
Separators, 2-3 
SET procedures, 9-33, 9-34 
SET$INTERRUPT procedure, 9-41 
SET$REAL$MODE built-in procedure, 10-25 
Shared memory, to access or lock, 9-39 thru 9-41 
SHLD function, 9-25, 9-26 
SHL function, 9-23, 9-24 
SHRD function, 9-25. 9-26 
SHR function, 9-23, 9-24 
Side effect, 8-5 
SIGN flag, 10-3 
SIGNED function, 9-19 
Signed integer data type built-in, 9-21 
SIZE function, 9-4 
SMALL control. 11-48 
SKIP functions, 9-31,9-32 
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Source code, to insert compiler control line, 1 1-1 

Special characters, 2-3 

Stack 

Base and pointer registers, to access, 10-6 
STACKBASE variable, 10-6 
STACKPTR variable, 10-6 
Statements 

Access output port, 10-7, 10-8 

ADJUST$RPL statement, 10-20, 10-21 

Array declaration, 4-2 

Arrays within structures, 4-4, 4-5 

Assignment, 5-20 thru 5-28 

AT attribute, 3-29 thru 3-31 

CALL, 8-1 thru 8-7, 8-13, 10-8 thru 10-38 

CAUSE$INTERRUPT, 8-13, 10-1 

Conditional IF/THEN/ELSE statements, 6-13, 6-14 

DEC statement, 10-4, 10-5 

DECLARE, 3-1 thru 3-5 
Scope, 7-1,7-2, 7-5 thru 7-8 

Declaring based variables, 3-26 thru 3-29 

DISABLE, 8-11, 10-1 

DO, 6-1 thru 6-10 

DO CASE, 6-4 

ENABLE, 8-11, 10-1 

END, 6-10 

GET$REAL$ERROR, 10-25 
GET$SEGMENT$LIMIT statement, 10-19 
GOTO, 6-14, 6-15 

Restrictions, 7-9 thru 7-12 

To exit procedure, 8-8 
HALT, 8-12, 10-2 
IF/THEN/ELSE, 6-10 thru 6-14 
INITIAL, 3-5 thru 3-9 

Label declarations, for intermodule reference, 3-13 
LITERALLY declarations, 3-11, 3-12 
Null, 6-5 
PROCEDURE 

Declaration, 8-1 thru 8-5 

Definition, 1-3 
RETURN, 8-8 

Return value of input port, 10-7 



SCL, SCR built-in functions, 10-3, 10-4 
SEGMENT$READABLE statement, 10-20 
SEGMENT$WRITABLE statement, 10-20 
Structure declaration, 4-3 
String 

Constant as an operand, 5-3 

Manipulation procedures and functions, 9-27 thru 9-35 
Strings, 2-6, 2-7 
Structures, 4-3 thru 4-7 

Return size, 9-4 
Subscript, 4-2, 4-3 

Substitution (characters/ values/quantities), 3-11, 3-12 
Subsystems, 13-8 thru 13-14, 13-16 
SUBTITLE control, 11-58 
Symbolic 

Constants, to name, 2-4 

Names, 3-1 
SYMBOLS control, 1 1-5, 1 1-1 1 , 1 1-57 
Syntax, Appendix C 

T 

Tables, list of, xv, xvi 

TASK$REGISTER variable, 10-11 

Temporary-real format (80-bit), 3-19, 3-20 

TESTSREGISTER built-in array, 10-17 

TIME procedure, 9-38 

TITLE control, 11-6, 11-11, 11-57 

Tokens, 2-3 

Transfers, GOTO, 7-9 

Translate string procedure, 9-34 

Translation, value and type, see Type conversion 

TSS, G-3, G-4 

TYPE control, 1 1-6, 1 1-7, 1 1-58 
Type conversion 

Explicit, 9-4 thru 9-22 

Implicit, 5-22 thru 5-25 
Typed procedure, 8-4 thru 8-8 
Types, 3-13 thru 3-24 
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u 

UDI, example using procedures, see Chapter 12 

Underscore, 2-3, 2-4 

Unmasked 

Error, 10-22 

Underflow, G-14 
UNSIGN function, 9-20 
Unsigned binary data type built-ins, 9-20 

Updating 8086 or 80286 code, see WORD16/WORD32 mapping 
Updating code, D-l thru D-4 
Uppercase characters, 2-1 

V 

Value 

Conversion, explicit, 9-4 thru 9-22 
Overflow, 11-41 

Pointer, segmentation controls, 13-3 thru 13-7 
Variable 

Array, 3-1, 3-2, 3-27 

Based, 2-39, 3-26, 8-9 

Built-ins, Chapters 9, 10 

Obtaining information about, 9-2 thru 9-4 

Scalar, 3-1 

Structure, 3-1, 3-2 

To assign 
Multiple values, 5-26, 5-27 
Value, 5-20 thru 5-28 

To declare, 3-1 thru 3-5 

To name, 2-4 
Vectors, interrupt, to set, 9-41 , 9-42 

w 

WAIT$FOR$INTERRUPT 

Built-in procedure, 10-27, 10-28 

Procedure. G-8, G-9 
Warning messages, Chapter 14 
WHILE, DO block, 6-1, 6-6 
Whole-number constant, 5-1, 5-2 
WORD, conversions from, 9-14 thru 9-16, 9-18 

WORD 1 6/ WORD32 control, 11-6, 11-7, 11-12 thru 11-15, 11-58 thru 11-61 
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WORD16/WORD32 mapping, 3-31 thru 3-34, 9-45, 9-46, 10-28, 10-29, 

11-58 thru 11-61 
Write string procedure, 10-9, 10-10 

X 

XLAT procedure, 9-33 

XREF control, 11-6, 11-10, 11-11, 11-61 

z 

ZERO flag, 10-3 
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